[
  {
    "content": "Documentation Data flowing from Devices via Hono to Business Applications and back The place of Eclipse Hono™ is within an IoT cloud. The goal is simplified device connectivity for Business Applications (or Solutions). It abstracts away the multiple specifics of different device-side connection protocols from a backend application perspective. Hono defines a small set of APIs to communicate in a unified way with very different devices, whether they use, for example, connection-oriented protocols such as MQTT and AMQP 1.0 or stateless protocols such as HTTP. As a result, Hono frees developers of IoT backend applications from the need to know device protocols in detail and allows them to add or change connection protocols without having to modify their applications.\nFor each supported connection protocol, Hono contains a microservice called Protocol Adapter, which maps the connection protocol of the device to Hono’s APIs. Those APIs are offered via a central messaging system. Each of the messaging APIs has a so-called northbound API for the Business Applications. The southbound APIs are used by protocol adapters to forward messages from devices to the applications and vice versa. Messages flowing from devices to Business Applications are called downstream messages since this is the primary communication direction in practice. The other communication direction is called upstream. These are messages sent from a Business Application to a device via the Command \u0026 Control API.\nThe APIs defined by Hono for messaging are Telemetry, Event, and Command \u0026 Control. The Telemetry API is intended to send arbitrary data, e.g. from sensors, downstream. Events are downstream messages as well, intended less frequent but more important messages. Depending on the provided messaging network, events can be persisted and delivered later on if an application faces a limited downtime. The Command \u0026 Control API allows to send messages, like commands, from northbound applications upstream and optionally return a response from a device.\nThe Getting Started guide helps to familiarize oneself with Hono by practical example. If interested in a specific protocol, the corresponding User Guide explains the usage comprehensively.\nTo learn the concepts more in-depth, start reading about the architecture and Hono’s concept of a Device Identity. The concept page Multi-tenancy explains how Hono allows isolating multiple sets of devices and data. Connecting Devices shows different ways to connect a device (directly or via a gateway), and Device Provisioning explains some options to register devices in Hono.\nTopics related to the operation of Hono are explained in the Admin Guide and the Deployment documentation.\n",
    "description": "",
    "tags": null,
    "title": "Documentation",
    "uri": "/hono/docs/2.7/"
  },
  {
    "content": "This guide will walk you through an interactive example usage scenario of Eclipse Hono. You will learn how devices can use Hono’s protocol adapters to publish telemetry data and events using both HTTP and/or MQTT. You will also see how downstream applications can consume this data using Hono’s north bound API regardless of the communication protocols used by the devices.\nPrerequisites for the Getting started Guide This guide requires several tools to be installed on your computer. During the course of this guide, the devices publishing data will be represented by means of running some command line tools for posting HTTP requests and for publishing MQTT packets.\nCurl HTTP Command Line Client The curl command is used in this guide for registering devices with Hono and for simulating a device publishing data using HTTP. On most *nix like systems curl will probably already be installed. Otherwise, please refer to the Curl project page for installation instructions.\nMosquitto MQTT Command Line Client The mosquitto_pub command is used in this guide for simulating a device publishing data using the MQTT protocol. Please refer to the Mosquitto project page for installation instructions, if you do not have it installed already.\nInfo The installation of the Mosquitto command line client is optional. If you do not install it then you will not be able to simulate an MQTT based device but otherwise will be able to get the same results described in this guide.\nHono Command Line Client The Hono command line client is used in this guide for simulating an application that consumes telemetry data and events published by devices. The client is available from Hono’s download page.\nTip The command line client is available in two variants:\nA Java Archive that requires a Java Runtime Environment to be installed locally and a x86_64 Linux executable that can be run from a shell directly. The former variant works on all platforms where Java is available and will be used during the remainder of this guide. The latter variant should work on modern Linux distributions and can be used by replacing java -jar hono-cli-*-exec.jar with just the name of the executable file.\nNote that when using the native executable, the root CA certificates included in the executable will be used. To use the (possibly more up to date) local CA certificates instead, add the --ca-file CLI parameter with the path of the certificates (e.g. --ca-file /etc/ssl/certs/ca-certificates.crt).\nHono Instance The most important prerequisite is, of course, a Hono instance that you can work with.\nThe most straightforward option to use for this guide is the Hono Sandbox which is running on infrastructure provided by the Eclipse Foundation and which is publicly accessible from the internet.\nUsing the Sandbox, there is no need to set up your own Hono instance locally. However, it requires several non-standard ports being accessible from your computer which may not be the case, e.g. if you are behind a firewall restricting internet access to a few standard ports only.\nYou can verify if you can access one of the non-standard ports of the Sandbox by running the following command and comparing the output:\ncurl -sIX GET https://hono.eclipseprojects.io:28443/v1/tenants/DEFAULT_TENANT If you get output like this\nHTTP/1.1 200 OK etag: 89d40d26-5956-4cc6-b978-b15fda5d1823 content-type: application/json; charset=utf-8 content-length: 260 you should be able to use the Sandbox. However, if the curl command failed to execute, you will need to set up a local Hono instance. You can choose between using Apache Kafka™ as the messaging infrastructure or AMQP 1.0 based infrastructure using Apache Qpid™ Dispatch Router and Apache ActiveMQ™ Artemis. Please select the tab below that matches your chosen type of messaging infrastructure and follow the instructions given there.\nSandbox Local Instance using Kafka Local Instance using AMQP 1.0 Hono consists of a set of microservices which are deployed as Docker containers. The diagram below provides an overview of the containers that are part of the Hono Sandbox deployment.\nComponents of the Hono Sandbox deployment Hono Instance An HTTP Adapter instance that exposes Hono’s Telemetry and Event APIs as URI resources. An MQTT Adapter instance that exposes Hono’s Telemetry and Event APIs as a generic MQTT topic hierarchy. An AMQP Adapter instance that exposes Hono’s Telemetry and Event APIs as a set of AMQP 1.0 addresses. A Command Router instance that receives Command \u0026 Control messages and forwards them to protocol adapters. A Device Registry instance that manages registration information and issues device registration assertions to protocol adapters. An Auth Server instance that authenticates Hono components and issues tokens asserting identity and authorities. Kafka Cluster An Apache Kafka broker instance that downstream applications connect to in order to consume telemetry data and events from devices and to send Command \u0026 Control messages to devices. An Apache Zookeeper instance that is required by the Kafka cluster. Monitoring Infrastructure A Prometheus instance for storing metrics data from services and protocol adapters. A Grafana instance providing a dashboard visualizing the collected metrics data. In the example scenario used in the remainder of this guide, the devices will connect to the HTTP and MQTT adapters in order to publish telemetry data and events. The devices will be authenticated using information stored in the Device Registry. The data is then forwarded downstream to the example application via the Kafka broker.\nRun the following commands to create the hono.env file which will be used during the remainder of this guide to set and refresh some environment variables:\ncat \u003c\u003cEOS \u003e hono.env export REGISTRY_IP=hono.eclipseprojects.io export HTTP_ADAPTER_IP=hono.eclipseprojects.io export MQTT_ADAPTER_IP=hono.eclipseprojects.io export KAFKA_IP=hono.eclipseprojects.io export APP_OPTIONS=\"--sandbox\" export CURL_OPTIONS= export MOSQUITTO_OPTIONS='--cafile /etc/ssl/certs/ca-certificates.crt' EOS Verify that the hono.env file has been created in your current working directory:\ncat hono.env export REGISTRY_IP=hono.eclipseprojects.io export HTTP_ADAPTER_IP=hono.eclipseprojects.io export MQTT_ADAPTER_IP=hono.eclipseprojects.io export KAFKA_IP=hono.eclipseprojects.io export APP_OPTIONS=\"--sandbox\" export CURL_OPTIONS= export MOSQUITTO_OPTIONS='--cafile /etc/ssl/certs/ca-certificates.crt' In order to set up an instance of Hono running on your local computer using Apache Kafka as the messaging infrastructure, follow these steps:\nPlease refer to the Kubernetes installation instructions for setting up a local single-node Minikube cluster. Make sure to run minikube tunnel in order to support creating Kubernetes services of type LoadBalancer. Follow the instructions given in the README of Hono’s Helm chart in order to install Hono with a single-node Kafka instance to your local Minikube cluster. Hono consists of a set of microservices which are deployed as Docker containers. The diagram below provides an overview of the containers that are part of the example deployment of Hono on the local Minikube cluster.\nComponents of the example Hono deployment using Kafka Hono Instance An HTTP Adapter instance that exposes Hono’s Telemetry and Event APIs as URI resources. An MQTT Adapter instance that exposes Hono’s Telemetry and Event APIs as a generic MQTT topic hierarchy. An AMQP Adapter instance that exposes Hono’s Telemetry and Event APIs as a set of AMQP 1.0 addresses. A Command Router instance that receives Command \u0026 Control messages and forwards them to protocol adapters. A Device Registry instance that manages registration information and issues device registration assertions to protocol adapters. An Auth Server instance that authenticates Hono components and issues tokens asserting identity and authorities. Kafka Cluster An Apache Kafka broker instance that downstream applications connect to in order to consume telemetry data and events from devices and to send Command \u0026 Control messages to devices. An Apache Zookeeper instance that is required by the Kafka cluster. Monitoring Infrastructure A Prometheus instance for storing metrics data from services and protocol adapters. A Grafana instance providing a dashboard visualizing the collected metrics data. In the example scenario used in the remainder of this guide, the devices will connect to the HTTP and MQTT adapters in order to publish telemetry data and events. The devices will be authenticated using information stored in the Device Registry. The data is then forwarded downstream to the example application via the Kafka broker.\nOnce Hono has been deployed to your local cluster, run the following commands to create the hono.env file which will be used during the remainder of this guide to set and refresh some environment variables:\necho \"export REGISTRY_IP=$(kubectl get service eclipse-hono-service-device-registry-ext --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e hono.env echo \"export HTTP_ADAPTER_IP=$(kubectl get service eclipse-hono-adapter-http --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e\u003e hono.env echo \"export MQTT_ADAPTER_IP=$(kubectl get service eclipse-hono-adapter-mqtt --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e\u003e hono.env KAFKA_IP=$(kubectl get service eclipse-hono-kafka-0-external --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono) TRUSTSTORE_PATH=/tmp/truststore.pem kubectl get configmaps eclipse-hono-example-trust-store --template=\"{{index .data \\\"ca.crt\\\"}}\" -n hono \u003e ${TRUSTSTORE_PATH} echo \"export APP_OPTIONS='-H ${KAFKA_IP} -P 9094 -u hono -p hono-secret --ca-file ${TRUSTSTORE_PATH} --disable-hostname-verification'\" \u003e\u003e hono.env echo \"export CURL_OPTIONS='--insecure'\" \u003e\u003e hono.env echo \"export MOSQUITTO_OPTIONS='--cafile ${TRUSTSTORE_PATH} --insecure'\" \u003e\u003e hono.env Verify that the hono.env file has been created in your current working directory:\ncat hono.env export REGISTRY_IP=(host name/IP address) export HTTP_ADAPTER_IP=(host name/IP address) export MQTT_ADAPTER_IP=(host name/IP address) export APP_OPTIONS='-H (host name/IP address) -P 9094 -u hono -p hono-secret --ca-file /tmp/truststore.pem --disable-hostname-verification' export CURL_OPTIONS='--insecure' export MOSQUITTO_OPTIONS='--cafile /tmp/truststore.pem --insecure' In order to set up an instance of Hono running on your local computer using Apache Qpid as the messaging infrastructure, follow these steps:\nPlease refer to the Kubernetes installation instructions for setting up a local single-node Minikube cluster. Make sure to run minikube tunnel in order to support creating Kubernetes services of type LoadBalancer. Follow the instructions given in the README of Hono’s Helm chart in order to install Hono with a single-node Qpid Dispatch Router instance to your local Minikube cluster. Hono consists of a set of microservices which are deployed as Docker containers. The diagram below provides an overview of the containers that are part of the example deployment of Hono on the local Minikube cluster.\nComponents of the example Hono deployment using AMQP 1.0 Hono Instance An HTTP Adapter instance that exposes Hono’s Telemetry and Event APIs as URI resources. An MQTT Adapter instance that exposes Hono’s Telemetry and Event APIs as a generic MQTT topic hierarchy. An AMQP Adapter instance that exposes Hono’s Telemetry and Event APIs as a set of AMQP 1.0 addresses. A Command Router instance that receives Command \u0026 Control messages and forwards them to protocol adapters. A Device Registry instance that manages registration information and issues device registration assertions to protocol adapters. An Auth Server instance that authenticates Hono components and issues tokens asserting identity and authorities. AMQP Network An Apache Qpid Dispatch Router instance that downstream applications connect to in order to consume telemetry data and events from devices and to send Command \u0026 Control messages to devices. An Apache ActiveMQ Artemis instance serving as the persistence store for events. Monitoring Infrastructure A Prometheus instance for storing metrics data from services and protocol adapters. A Grafana instance providing a dashboard visualizing the collected metrics data. In the example scenario used in the remainder of this guide, the devices will connect to the HTTP and MQTT adapters in order to publish telemetry data and events. The devices will be authenticated using information stored in the Device Registry. The data is then forwarded downstream to the example application via the AMQP Messaging Network.\nOnce Hono has been deployed to your local cluster, run the following commands to create the hono.env file which will be used during the remainder of this guide to set and refresh some environment variables:\necho \"export REGISTRY_IP=$(kubectl get service eclipse-hono-service-device-registry-ext --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e hono.env echo \"export HTTP_ADAPTER_IP=$(kubectl get service eclipse-hono-adapter-http --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e\u003e hono.env echo \"export MQTT_ADAPTER_IP=$(kubectl get service eclipse-hono-adapter-mqtt --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono)\" \u003e\u003e hono.env TRUSTSTORE_PATH=/tmp/truststore.pem kubectl get configmaps eclipse-hono-example-trust-store --template=\"{{index .data \\\"ca.crt\\\"}}\" -n hono \u003e ${TRUSTSTORE_PATH} AMQP_NETWORK_IP=$(kubectl get service eclipse-hono-dispatch-router-ext --output=\"jsonpath={.status.loadBalancer.ingress[0]['hostname','ip']}\" -n hono) echo \"export APP_OPTIONS='--amqp -H ${AMQP_NETWORK_IP} -P 15671 -u consumer@HONO -p verysecret --ca-file ${TRUSTSTORE_PATH} --disable-hostname-verification'\" \u003e\u003e hono.env echo \"export CURL_OPTIONS='--insecure'\" \u003e\u003e hono.env echo \"export MOSQUITTO_OPTIONS='--cafile ${TRUSTSTORE_PATH} --insecure'\" \u003e\u003e hono.env Verify that the hono.env file has been created in your current working directory:\ncat hono.env export REGISTRY_IP=(host name/IP address) export HTTP_ADAPTER_IP=(host name/IP address) export MQTT_ADAPTER_IP=(host name/IP address) export APP_OPTIONS='--amqp -H (host name/IP address) -P 15671 -u consumer@HONO -p verysecret --ca-file /tmp/truststore.pem --disable-hostname-verification' export CURL_OPTIONS='--insecure' export MOSQUITTO_OPTIONS='--cafile /tmp/truststore.pem --insecure' Info We will use the hono.env file during the rest of this guide to set and refresh environment variables that contain the Hono API endpoint addresses and the example device credentials.\nRegistering Devices When a device tries to connect to one of Hono’s protocol adapters, the protocol adapter first tries to authenticate the device using information kept in the Device Registry. The information maintained in the registry includes the tenant (a logical scope) that the device belongs to, the device’s unique identity within the tenant and the credentials used by the device for authentication.\nBefore a device can connect to Hono and publish any data, the corresponding information needs to be added to the Device Registry.\nCreating a new Tenant Register a tenant that is configured for Kafka based messaging using Hono’s Device Registry’s management HTTP API:\n# in the folder that contains the hono.env file source hono.env curl -i -X POST ${CURL_OPTIONS} -H \"content-type: application/json\" --data-binary '{ \"ext\": { \"messaging-type\": \"kafka\" } }' https://${REGISTRY_IP}:28443/v1/tenants HTTP/1.1 201 Created etag: becc93d7-ab0f-48ec-ad26-debdf339cbf4 location: /v1/tenants/85f63e23-1b78-4156-8500-debcbd1a8d35 content-type: application/json; charset=utf-8 content-length: 45 {\"id\":\"85f63e23-1b78-4156-8500-debcbd1a8d35\"} The response will contain a randomly generated tenant identifier. It will probably be different from the value shown in the example above. In any case, save it in an environment variable by adding a line like this to the hono.env file created earlier:\necho \"export MY_TENANT=85f63e23-1b78-4156-8500-debcbd1a8d35\" \u003e\u003e hono.env Make sure to actually use the tenant identifier returned by Hono’s device registry.\nAdding a Device to the Tenant Register a device using Hono’s Device Registry’s management HTTP API:\n# in the folder that contains the hono.env file source hono.env curl -i -X POST ${CURL_OPTIONS} https://${REGISTRY_IP}:28443/v1/devices/${MY_TENANT} HTTP/1.1 201 Created etag: 68eab243-3df9-457d-a0ab-b702e57c0c17 location: /v1/devices/85f63e23-1b78-4156-8500-debcbd1a8d35/4412abe2-f219-4099-ae14-b446604ae9c6 content-type: application/json; charset=utf-8 content-length: 45 {\"id\":\"4412abe2-f219-4099-ae14-b446604ae9c6\"} The response will contain a randomly generated device identifier. It will probably be different from the value shown in the example above. In any case, save it in an environment variable by adding a line like this to the hono.env file created earlier:\necho \"export MY_DEVICE=4412abe2-f219-4099-ae14-b446604ae9c6\" \u003e\u003e hono.env Make sure to actually use the device identifier returned by Hono’s device registry.\nSetting a Password for the Device Choose a (random) password and register it using Hono’s Device Registry’s management HTTP API (replace this-is-my-password with your password):\n# in directory that contains the hono.env file echo \"export MY_PWD=this-is-my-password\" \u003e\u003e hono.env source hono.env curl -i -X PUT ${CURL_OPTIONS} -H \"content-type: application/json\" --data-binary '[{ \"type\": \"hashed-password\", \"auth-id\": \"'${MY_DEVICE}'\", \"secrets\": [{ \"pwd-plain\": \"'${MY_PWD}'\" }] }]' https://${REGISTRY_IP}:28443/v1/credentials/${MY_TENANT}/${MY_DEVICE} HTTP/1.1 204 No Content etag: cf91fd4d-7111-4e8a-af68-c703993a8be1 Content-Length: 0 Starting the example Application The telemetry data produced by devices is usually consumed by downstream applications that use it to implement their corresponding business functionality. In this guide we will use the Hono command line client to simulate such an application. The client will connect to Hono’s north bound Telemetry and Event APIs, subscribe to all telemetry and event messages and log the messages to the console.\nOpen a new terminal window to run the client from the command line.\n# in directory that contains the hono.env file source hono.env # in directory where the hono-cli-*-exec.jar file has been downloaded to java -jar hono-cli-*-exec.jar app ${APP_OPTIONS} consume --tenant ${MY_TENANT} Publishing Telemetry Data to the HTTP Adapter Now that the downstream application is running, devices can start publishing telemetry data and events using Hono’s protocol adapters. First, you will simulate a device publishing data to Hono using the HTTP protocol.\nGo back to the original terminal and run:\ncurl -i -u ${MY_DEVICE}@${MY_TENANT}:${MY_PWD} ${CURL_OPTIONS} -H 'Content-Type: application/json' --data-binary '{\"temp\": 5}' https://${HTTP_ADAPTER_IP}:8443/telemetry HTTP/1.1 202 Accepted Content-Length: 0 If you have started the downstream application as described above, you should now see the telemetry message being output to the application’s console in the other terminal. The output should look something like this:\nt 4412abe2-f219-4099-ae14-b446604ae9c6 application/json {\"temp\": 5} {orig_adapter=hono-http, device_id=my-device, orig_address=/telemetry} You can publish more data simply by re-running the curl command above with arbitrary payload.\nThe HTTP Adapter also supports publishing telemetry messages using at least once delivery semantics. For information on how that works and additional examples for interacting with Hono via HTTP, please refer to the HTTP Adapter’s User Guide.\nPublishing Events to the HTTP Adapter In a similar way you can upload events:\ncurl -i -u ${MY_DEVICE}@${MY_TENANT}:${MY_PWD} ${CURL_OPTIONS} -H 'Content-Type: application/json' --data-binary '{\"alarm\": \"fire\"}' https://${HTTP_ADAPTER_IP}:8443/event HTTP/1.1 202 Accepted Content-Length: 0 Again, you should see the event being logged to the console of the downstream application.\nPublishing Telemetry Data to the MQTT Adapter Devices can also publish data to Hono using the MQTT protocol. If you have installed the mosquitto_pub command line client, you can run the following command to publish arbitrary telemetry data to Hono’s MQTT adapter using QoS 0:\nmosquitto_pub -h ${MQTT_ADAPTER_IP} -p 8883 -u ${MY_DEVICE}@${MY_TENANT} -P ${MY_PWD} ${MOSQUITTO_OPTIONS} -t telemetry -m '{\"temp\": 5}' Again, you should now see the telemetry message being logged to console of the downstream application.\nThe MQTT Adapter also supports publishing telemetry messages using QoS 1. For information on how that works and additional examples for interacting with Hono via MQTT, please refer to the MQTT Adapter’s User Guide.\nPublishing Events to the MQTT Adapter In a similar way you can upload events:\nmosquitto_pub -h ${MQTT_ADAPTER_IP} -p 8883 -u ${MY_DEVICE}@${MY_TENANT} -P ${MY_PWD} ${MOSQUITTO_OPTIONS} -t event -q 1 -m '{\"alarm\": \"fire\"}' Again, you should now see the event being logged to console of the downstream application.\nCongratulations You have successfully connected a device to Hono and published sensor data for consumption by an application. The application consumed messages via Hono’s north bound API regardless of the transport protocol used by the device to publish the data.\nWhat to try next?\nContinue with the next sections to learn how applications can send commands to devices by means of the Command \u0026 Control API for Kafka and/or Command \u0026 Control API for AMQP 1.0. Check out the User Guides to explore more options for devices to connect to Hono using different transport protocols. Learn more about the managing tenants, devices and credentials using the Device Registry’s HTTP API. Advanced: Sending Commands to a Device The following example will guide you through an advanced feature of Hono. You will see how an application can send a command to a device and receive a response with the result of processing the command on the device. The communication direction here is exactly the other way round than with telemetry and events.\nThe following assumes that the steps in the Prerequisites for the Getting started Guide and Registering Devices sections above have been completed. To simulate the device, you can use the Mosquitto tools again while the Hono Command Line Client simulates the application as before.\nReceiving a Command With the mosquitto_sub command you simulate an MQTT device that receives a command. Create a subscription to the command topic in the terminal for the simulated device:\n# in directory that contains the hono.env file source hono.env mosquitto_sub -v -h ${MQTT_ADAPTER_IP} -p 8883 -u ${MY_DEVICE}@${MY_TENANT} -P ${MY_PWD} ${MOSQUITTO_OPTIONS} -t command///req/# Now that the device is waiting to receive commands, the application can start sending them.\nIn a new terminal window, start the command line client:\n# in directory that contains the hono.env file source hono.env # in directory where the hono-cli-*-exec.jar file has been downloaded to java -jar hono-cli-*-exec.jar app ${APP_OPTIONS} command hono-cli/app/command\u003e At the prompt, enter the following to send a one-way command with a JSON payload to the device:\now --tenant ${MY_TENANT} --device ${MY_DEVICE} -n setVolume --payload '{\"level\": 50}' In the terminal for the simulated device you should see the received command as follows\ncommand///req//setVolume {\"level\": 50} Sending a Response to a Command Now that you have sent a one-way command to the device, you may get to know request-response commands where the device sends a response to the application. A request-response command received from an application contains an identifier that is unique to each new command. The device must include this identifier in its response so that the application can correctly correlate the response with the request.\nIf you send a request-response command like this\nreq --tenant ${MY_TENANT} --device ${MY_DEVICE} -n setBrightness --payload '{\"level\": 87}' the application will wait up to 60 seconds for the device’s response.\nIn the terminal for the simulated device you should see the received command that looks like this\ncommand///req/10117f669c12-09ef-416d-88c1-1787f894856d/setBrightness {\"level\": 87} The topic segment between req and setBrightness is the request identifier that must be included in the response.\nYou can cancel the command mosquitto_sub in the terminal of the device (press the key combination Ctrl + C) to reuse the configuration with the environment variables for sending the response. The following example shows how a response can be sent via MQTT. Note that the actual identifier from the received command must be used.\nexport REQ_ID=10117f669c12-09ef-416d-88c1-1787f894856d mosquitto_pub -h ${MQTT_ADAPTER_IP} -p 8883 -u ${MY_DEVICE}@${MY_TENANT} -P ${MY_PWD} ${MOSQUITTO_OPTIONS} -t command///res/${REQ_ID}/200 -m '{\"current-level\": 87}' The 200 at the end of the topic is an HTTP status code that reports the result of processing the command to the application.\nIf the Command Line Client has successfully received the response in time, it will print a line to the console’s standard output:\nres 4412abe2-f219-4099-ae14-b446604ae9c6 200 application/octet-stream {\"current-level\": 87} The command line client will print an error message to System.err if the device does not respond to the command in time. By default, the client will wait for 60 seconds for the response, a longer timeout can be set using the -r option:\nreq --tenant ${MY_TENANT} --device ${MY_DEVICE} -n setBrightness --payload '{\"level\": 87}' -r 120 Congratulations You have successfully sent commands to a device and responded to them. For more information on Command \u0026 Control refer to Commands using HTTP and Commands using MQTT. The Command and Control Concepts page contains sequence diagrams that explain this in more detail.\n",
    "description": "Take a quick tour and learn how Hono can help you connect devices via HTTP and/or MQTT and how downstream applications can consume the data published by devices.",
    "tags": null,
    "title": "Getting started with Eclipse Hono",
    "uri": "/hono/docs/2.7/getting-started/"
  },
  {
    "content": "Concepts Understand the concepts behind Eclipse Hono™.\n",
    "description": "",
    "tags": null,
    "title": "Concepts",
    "uri": "/hono/docs/2.7/concepts/"
  },
  {
    "content": "This page describes how devices are represented and identified throughout Hono and its APIs.\nThe main purpose of Hono is to provide a uniform API for applications to interact with devices, regardless of the particular communication protocol the devices natively use. In order to do so, Hono uses a unique logical identifier to refer to each device individually.\nHono does not make any assumptions about the format of a device identifier (or device-id for short). It basically is a string which is defined at the time a device is being provisioned. Once created, the device can be referred to by this identifier when using Hono’s APIs until the device is being removed from the system.\nTenant Hono supports the logical partitioning of devices into groups called tenants. Each tenant has a unique identifier, a string called the tenant-id, and can be used to provide a logical grouping of devices belonging e.g. to the same application scope or organizational unit. Each device can thus be uniquely identified by the tuple (tenant-id, device-id). This tuple is broadly used throughout Hono’s APIs when addressing a particular device.\nDevice Registration Hono components use the Device Registration API to access device registration information. The API defines the assert Registration operation for verifying a device’s registration status.\nIn many real world scenarios there will already be a component in place which keeps track of devices and which supports the particular provisioning process being used to bring devices into life. In such cases it makes sense to simply implement the Device Registration API as a facade on top of the existing component.\nIn addition to that, Hono defines a Device Registry Management API, which can be implemented to take advantage of standardized operations for managing devices and credentials. This API is optional because Hono components do not require it during runtime.\nHono comes with a MongoDB and a JDBC based implementation of both APIs. The JDBC based implementation supports PostgreSQL and H2 out of the box. It can also be configured with an H2 based in-memory database which can be used for demonstration or testing purposes.\nDevice Authentication Devices connect to protocol adapters in order to publish telemetry data or events. Downstream applications consuming this data often take particular actions based on the content of the messages. Such actions may include simply updating some statistics, e.g. tracking the average room temperature, but may also trigger more serious activities like shutting down a power plant. It is therefore important that applications can rely on the fact that the messages they process have in fact been produced by the device indicated by a message’s source address.\nHono relies on protocol adapters to establish a device’s identity before it is allowed to publish downstream data or receive commands. Conceptually, Hono distinguishes between two identities\nan identity associated with the authentication credentials (termed the authentication identity or auth-id), and an identity to act as (the device identity or device-id). A device therefore presents an auth-id as part of its credentials during the authentication process which is then resolved to a device identity by the protocol adapter on successful verification of the credentials.\nIn order to support the protocol adapters in the process of verifying credentials presented by a device, the Credentials API provides means to look up secrets on record for the device and use this information to verify the credentials.\nThe Credentials API supports registration of multiple sets of credentials for each device. A set of credentials consists of an auth-id and some sort of secret information. The particular type of secret determines the kind of information kept. Please refer to the Standard Credential Types defined in the Credentials API for details. Based on this approach, a device may be authenticated using different types of secrets, e.g. a hashed password or a client certificate, depending on the capabilities of the device and/or protocol adapter.\nOnce the protocol adapter has resolved the device-id for a device, it uses this identity when referring to the device in all subsequent API invocations, e.g. when forwarding telemetry messages downstream.\nEvery device connecting to Hono needs to be registered in the scope of a single tenant as described above already. The Device Registration and Credentials APIs therefore require a tenant identifier to be passed in to their operations. Consequently, the first step a protocol adapter needs to take when authenticating a device is determining the tenant that the device belongs to.\nThe means used by a device to indicate the tenant that it belongs to vary according to the type of credentials and authentication mechanism being used.\nUsername/Password based Authentication The MQTT, HTTP and AMQP protocol adapters support authentication of devices with a username/password based mechanism. In this case, a protocol adapter verifies that the password presented by the device during connection establishment matches the password that is on record for the device in the device registry.\nDuring connection establishment the device presents a username and a password to the protocol adapter. For example, a device that belongs to tenant example-tenant and for which hashed-password credentials with an auth-id of device-1 have been registered, would present a username of device-1@example-tenant when authenticating to a protocol adapter.\nThe protocol adapter then extracts the tenant identifier from the username and invokes the Credentials API’s get Credentials operation in order to retrieve the hashed-password type credentials that are on record for the device.\nPre-Shared Key based Authentication The CoAP protocol adapter supports authentication of devices using a pre-shared key (PSK) as part of a DTLS handshake. In this case, the protocol adapter verifies that the PSK used by the device to generate the DTLS session’s pre-master secret is the same as the key contained in the credentials that are on record for the device in the device registry.\nDuring the DTLS handshake the device provides a psk_identity to the protocol adapter. For example, a device that belongs to tenant example-tenant and for which psk credentials with an auth-id of device-1 have been registered, would present a PSK identity of device-1@example-tenant during the DTLS handshake.\nThe protocol adapter then extracts the tenant identifier from the PSK identity and invokes the Credentials API’s get Credentials operation in order to retrieve the psk type credentials that are on record for the device. The psk contained in the credentials are then used by the protocol adapter to generate the pre-master secret of the DTLS session being negotiated with the client. If both, the device and the protocol adapter use the same key for doing so, the DTLS handshake will succeed and the device has been authenticated successfully.\nClient Certificate based Authentication Devices can also use an X.509 (client) certificate to authenticate to protocol adapters. In this case, the protocol adapter tries to verify that a valid chain of certificates can be established starting with the client certificate presented by the device up to one of the trusted root certificates configured for the device’s tenant.\nDuring connection establishment with the device, the protocol adapter tries to determine the tenant to which the device belongs and retrieve the tenant’s configuration information using the Tenant API. The adapter then uses the trust anchors that have been configured for the tenant to verify the client certificate.\nThe protocol adapter tries to look up the device’s tenant configuration using the Tenant API’s get Tenant Information operation. The adapter first invokes the operation using the issuer DN from the device’s client certificate. If that fails and if the device has included the Server Name Indication extension during the TLS handshake, the adapter extracts the first label of the first host name conveyed in the SNI extension and invokes the get Tenant Information operation with the extracted value as the tenant identifier. For example, a host name of my-tenant.hono.eclipseprojects.io would result in a tenant identifier of my-tenant being used in the look-up.\nInfo Labels in host names may only consist of letters, digits and hyphens. In order to be able to refer to tenants which have an identifier that consists of other characters as well, the Device Registry Management API supports registering an alias for a tenant which can be used as an alternate identifier when looking up tenant configuration information.\nBased on that, a tenant with identifier unsupported_id that has been registered using alias my-tenant, can be referred to by a device by means of including a host name like my-tenant.hono.eclipseprojects.io in the SNI extension.\nAfter having verified the client certificate using the trust anchor(s), the protocol adapter extracts the client certificate’s subject DN and invokes the Credentials API’s get Credentials operation in order to retrieve the x509-cert type credentials that are on record for the device.\nCertificate Revocation Checking (experimental) Hono supports OCSP based certificate revocation checking for client certificates presented by devices using client certificate based authentication. If this feature is enabled, the protocol adapter tries to verify the client certificate’s revocation status. The device with revoked or unknown certificate status is not allowed to connect to the protocol adapter. The adapter uses the OCSP responder URL that has been configured for the tenant or Authority Information Access (AIA) extension in the client certificate to retrieve the OCSP response. The response is then used to verify the client certificate’s revocation status. Revocation check can be configured using the Tenant resource of Device Registry Management API.\nOCSP revocation check is supported for all protocol adapters.\nInfo This feature is experimental and may be subject to change in future releases without further notice. Current implementation checks the revocation of end entity certificates only (with CA:FALSE in basic constraints extension). If OCSP revocation check is enabled and revocation status cannot be determined, the protocol adapter will reject the connection. Hono currently does not cache OCSP responses so frequent connections may cause high load on OCSP responders.\nJSON Web Token based Authentication The HTTP and MQTT protocol adapters support authentication of devices with a signed JSON Web Token (JWT) based mechanism. In this case, the protocol adapter tries to validate the token presented by the device using a public key on record.\nDuring connection establishment the device is expected to present the tenant identifier, authentication identifier and a valid and signed JWT to the protocol adapter. The information about the tenant and the authentication identifier can be presented to the protocol adapter in one of two ways:\nEither as claims inside the JSON Web Signature (JWS) payload, in which case the tenant-id and auth-id must be provided in the tid and sub (subject) claims respectively, and the aud (audience) claim must contain hono-adapter or via an adapter specific mechanism. For more information see HTTP or MQTT The JWT’s JOSE header MUST contain the typ parameter with value JWT and MUST contain the alg parameter indicating the algorithm that has been used to create the JWS signature. RS256, PS256, ES256 and their respective stronger variants are supported. The algorithm specified in the header must be compatible with at least one of the Raw Public Key type credentials registered for the device.\nThe JWS payload MUST contain the claims iat (issued at) and exp (expiration time) with values provided in Unix time. The iat claim marks the instant at which the token has been created and also marks the start of its validity period. It must not be too far in the past or the future (allowing 10 minutes for skew). The nbf (not before) claim is therefore not required and will be ignored. The exp claim marks the instant after which the token MUST be considered invalid. The lifetime of the token must be at most 24 hours plus skew.\nThe protocol adapter then invokes the Credentials API’s get Credentials operation in order to retrieve the rpk (raw public key) type credentials that are on record for the device. The key contained in the credentials is then used by the protocol adapter to verify the JWS signature.\n",
    "description": "",
    "tags": null,
    "title": "Device Identity",
    "uri": "/hono/docs/2.7/concepts/device-identity/"
  },
  {
    "content": "Hono is designed to structure the set of all internally managed data and data streams into strictly isolated subsets. This includes the registration data and credentials of devices, internal users that are used for authentication, and the Business Applications that are part of such subsets as well.\nThis way of strict isolation is generally known as multi-tenancy, where a tenant is the term for such a subset. Such an isolation is essential for enabling a scalable distributed architecture to handle independent subsets as if each subset had its own installation (which would be much harder to maintain and would not benefit from runtime cost sharing).\nHono’s multi-tenancy concept is based on handling tenants as own entities. All functionality of Hono is provided in the context of a previously created tenant - except the creation of a tenant itself.\nIn the following the different aspects of multi-tenancy in Hono are addressed and a full overview of the concept is given.\nThe Tenant API By means of the Tenant API Hono handles tenants as own entities. The API defines how to retrieve the details of a specific tenant. This offers the possibility to handle arbitrary properties on the level of a tenant (see e.g. Protocol adapter configuration). For convenience, there are CRUD operations for the handling of tenants, which can be found in the Device Registry Management API.\nProtocol Adapters respect the Tenant API When a device connects to one of Hono’s protocol adapters, the adapter determines the tenant this device belongs to. How this is done is described in the User Guide. After the tenant is determined, the adapter retrieves the details of the determined tenant by means of the Tenant API. Only if the tenant exists and is enabled the adapter further processes the data of the device that is connecting. Otherwise the connection will be closed.\nProtocol Adapter Configuration Protocol adapters retrieve parts of their configuration on a tenant level by using the details of the determined tenant. This includes e.g. if a specific protocol adapter is enabled at all for this tenant, allowing to define tenants with only a subset of Hono’s functionality. This feature is foreseen to be especially important for production setups.\nExample: a tenant that\ncan use the MQTT protocol adapter but is not allowed to use the HTTP protocol adapter Please refer to the Tenant API to find out which protocol adapter properties can be configured at the tenant level.\nAMQP 1.0 Endpoints The AMQP 1.0 endpoints for all APIs of Hono are scoped to a tenant, by using the scheme \u003capi-name\u003e/TENANT/....\nExamples:\ntelemetry/TENANT event/TENANT registration/TENANT This separates the AMQP endpoints from each other on a tenant level.\nThe only exception to this is the Tenant API which does not follow this scheme since it is addressing the tenants themselves.\nDevices and Tenants A physical device will usually be represented in Hono as an entity in the device registry, having a unique identity and belonging to exactly one tenant. All data sent from a device, as well as from the application to the device, is therefore treated as belonging to the corresponding tenant.\nThe following diagram shows the relation between tenants, devices and their credentials:\nTenants, Devices and Credentials Tenant based Flow Control An important detail in Hono’s architecture is that data sent downstream is transported via the tenant scoped AMQP 1.0 links from the protocol adapters to the AMQP 1.0 network. Each tenant has its own pair of AMQP 1.0 links and is treated independently from other tenants regarding the back pressure mechanism that AMQP 1.0 offers. This enables a Business application to limit the rate at which it consumes AMQP 1.0 messages per tenant.\nFor the other direction, when commands are sent from the application to the device, the rate is also limited per tenant.\nAuthorization at Tenant Level Hono’s components authenticate each other by means of the Authentication API. The returned token for a successful authentication contains authorization information that is addressing the AMQP 1.0 endpoints. Since the endpoints (as outlined above) are scoped to a tenant, this enables to configure tenants that are authorized to only a subset of Hono’s full functionality.\nExample: a tenant (defined by means of authorization configuration) that\nis allowed to send telemetry data downstream but is not allowed to send event data This is done by not including the event endpoint in the authorization token for these tenants.\nBusiness Applications and Tenants The northbound Business applications are always connecting to the AMQP 1.0 endpoints of Hono. By means of the authentication and authorization setup and the fact that the endpoints are scoped to a tenant, the Business application is only acting in the context of one tenant.\nSeparation of Tenants Tenants are separated from each other in all of Hono’s components. Here is a summary of how this is implemented:\nthe registration of devices are strictly scoped to a tenant the credentials of devices are strictly scoped to a tenant protocol adapters can be enabled/disabled for a tenant the downstream data flow is isolated for every tenant the upstream data flow (Command \u0026 Control) is isolated for every tenant Business applications need to authenticate to the AMQP 1.0 network and are by that mechanism scoped to their tenant Hints for Production To be flexible for the different needs of production setups, Hono tries to make as few assumptions about the combination of the different APIs as possible. This means e.g. that the Device Registry does not enforce referential integrity of the APIs:\ndevices can be created for a tenant that is not existing (yet) credentials can be created for a tenant and/or a device that is not existing (yet) tenants can be deleted and leave their scoped devices and credentials still in the configuration (which may not be usable anymore, since the tenant is missing) These are points that production setups may want to implement differently.\n",
    "description": "",
    "tags": null,
    "title": "Multi-Tenancy",
    "uri": "/hono/docs/2.7/concepts/tenancy/"
  },
  {
    "content": "This page describes how devices are provisioned in Hono, i.e. how their digital representation is generated. For each device, registration information is stored that defines a device identity. Each device belongs to exactly one tenant. Each device must have at least one set of credentials that are used to authenticate to Hono.\nTo get an understanding of what is meant by the terms tenant, device registration and credentials, it is recommended to read the Device Identity page first.\nSo in order to use a device with Hono, it has to be provisioned. This means that registration information and at least one credential record must be stored in the device registry.\nThere are different ways to perform device provisioning.\nManual Device Provisioning Devices can be provisioned using Hono’s Device Registry Management API via HTTP.\nIf the desired tenant does not yet exist, it must be created first. How to do this is described in the tenants section of the Device Registry Management API.\nThe actual Device Provisioning is then performed by adding devices as described under devices section of the Device Registry Management API. This creates both a device identity and an (empty) credentials record. The last step is to add real credentials as described in the credentials section of the Device Registry Management API.\nAutomatic Device Provisioning The term Auto-Provisioning denotes a feature of Hono where the Device Registry automatically generates the credentials and registration information for a device the first time it connects. Auto-Provisioning is supported by Hono’s protocol adapters for devices that authenticate with client certificates or for devices that are connected via a gateway.\nPrerequisites Hono does not require a specific Device Registry implementation, but only specifies a set of APIs that must be provided by a compatible implementation. Since the main part of the Auto-Provisioning has to be done by the Device Registry, the used implementation must explicitly support this feature.\nClient certificate based Auto-Provisioning This feature can be enabled by supplying a certificate authority (CA) for a certain tenant:\nStep 1: Configure the Tenant The CA to be used by the devices needs to be configured. The following tasks must be performed:\nCreate tenant Configure the trusted CA for the tenant Enable the feature for the CA If the Device Registry implementation provides the Management API, this could be done in a single step. For details refer to the Tenant API specification.\nThe Device Registry generates a unique device identifier during auto-provisioning. If auto-provisioning-device-id-template is configured in the corresponding tenant’s CA entry, then the device registry generates the device identifier based on the configured template. If not configured, then a random unique device identifier is generated. Refer to the Device Registry Management API for more details on how to configure a tenant’s trusted CA authority for that.\nThe Device Registry creates device credentials during auto-provisioning. If auth-id-template is configured in the corresponding tenant’s CA entry, then the device registry generates the credentials authentication identity based on the configured template. If not configured, then subject DN of the device certificate is used as authentication identity. Refer to the Device Registry Management API for more details on how to configure a tenant’s trusted CA authority for that.\nStep 2: Connect an unregistered Device to Hono Automatic Provisioning of a Device Hono’s protocol adapters query the APIs of the Device Registry during Device Authentication. First, the Tenant API is queried. If the Tenant configuration returned contains the CA used for authentication and the feature is switched on for this CA, the protocol adapter assumes that automatic provisioning must be performed. It puts the device’s certificate into the query to enable the device registry to do the provisioning.\nIf the Device Registry does not find any credentials for the device, it takes the information from the client certificate to create both credentials and device registration data for it.\nThe Device Registry is expected to perform the following steps:\nGenerate a unique device-id Create device Create credentials Send a Device Provisioning Notification Optional: Provision device in external systems After successfully sending a device provisioning notification, the corresponding device registration is updated with auto-provisioning-notification-sent as true. Whenever a protocol adapter sends a request to the Device Registry to fetch credentials, this property is verified provided that the device or gateway is auto-provisioned. If it is false a device provisioning notification is sent followed by setting auto-provisioning-notification-sent to true. This is to ensure that the notification is sent at least once.\nThe newly created credentials are returned to the protocol adapter in the response as if they had been present before.\nThe following query of the Device Registration API returns the previously generated registration data.\nThe provisioning is, of course, a one-time action, on subsequent connections the APIs simply return the stored records.\nAutomatic Gateway Provisioning Auto-provisioning of gateways involves the same steps as Automatic Device Provisioning. An extra attribute namely auto-provision-as-gateway is needed in the tenant’s trusted CA configuration to enable auto-provisioning of gateways. If this attribute is set to true then the device registry provisions any unregistered devices that authenticate with a client certificate issued by this tenant’s trusted CA as gateways, provided that the attribute auto-provisioning-enabled is also set to true. Refer to the Device Registry Management API for more details on the tenant’s trusted CA configuration.\nGateway based Auto-Provisioning It refers to auto-provisioning of edge devices that are connected via gateways. Enabling gateway based auto-provisioning requires configuration of the gateway device:\nStep 1: Configure the Gateway Device The gateway device must have the corresponding authority (auto-provisioning-enabled) set. Refer to the Management API for creating or updating a corresponding device.\nStep 2: Connect an unregistered Device via Gateway to Hono Automatic Provisioning of a Device via gateway The yet unregistered edge device sends telemetry data via a gateway (1) to a protocol adapter which then checks if the edge device is already registered by calling the assert operation of Device Registration API (2). If the device registration service finds that the device isn’t registered yet and the gateway has the auto-provisioning-enabled authority set, it creates the edge device (3).\nSubsequently, after it made sure that it hasn’t already done so, it sends an Device Provisioning Notification with the hono_registration_status application property being set to NEW to the AMQP network (4). Once the event has been accepted by the peer (5), the registration service marks the event as delivered (6). The persistent flag guarantees that the Device Provisioning Notification is sent AT_LEAST_ONCE. (NB: applications may receive duplicates of the Device Provisioning Notification!).\nFinally, the device registration service returns the registration information to the protocol adapter (7) which then forwards the telemetry data to the AMQP network (8).\n",
    "description": "",
    "tags": null,
    "title": "Device Provisioning",
    "uri": "/hono/docs/2.7/concepts/device-provisioning/"
  },
  {
    "content": "One of the most important features of Eclipse Hono™ is to abstract away the specific communication protocols used by devices. This page describes the different ways of how devices can be connected to Hono.\nBefore a device can connect to Hono and upload data or receive commands from downstream applications, it needs to be provisioned to the system. As part of device provisioning, the device is associated with the tenant that it belongs to and gets assigned a logical identifier which is unique within the tenant.\nDevices can be generally partitioned into two groups: devices which natively support the Internet Protocol (IP) for communication and devices that don’t.\nDevices falling into the former group can connect to Hono directly using any of the IP based protocols supported by Hono’s protocol adapters. Devices from the latter group often use radio based or serial line communication protocols that are limited to a local area and require a gateway in order to connect to one of Hono’s protocol adapters via IP.\nThe diagram below shows a device that supports the MQTT protocol and connects directly to Hono’s MQTT protocol adapter and another device that uses Bluetooth LE for connecting locally to a gateway which then connects to Hono’s MQTT adapter.\nConnecting to a Protocol Adapter directly The most straight forward scenario is a device connecting to one of Hono’s protocol adapters directly via IP based network infrastructure. For this to work, the device needs to use a communication protocols supported by one of the adapters and needs to be able to use the resource endpoints exposed by that particular protocol adapter as described in its user guide.\nIn this case the connected device’s identity will be resolved as part of authentication during connection establishment. For this to work, a set of credentials needs to be provisioned for the device which needs to be appropriate for usage with one of the adapter’s supported authentication schemes.\nConnecting via a Device Gateway In some cases, a device may not be able to directly connect to one of Hono’s protocol adapters. An example is a device that uses a serial bus or radio waves for local communication. Such devices can be connected to a protocol adapter by means of a device gateway which acts on behalf of the device(s) when communicating with Hono. A device gateway is often implemented as a (small) hardware box close to the devices, running some gateway software which translates hence and forth between the device and one of Hono’s protocol adapters.\nFrom the perspective of a protocol adapter, the gateway looks just like any other device having its own device identity and credentials.\nThe following diagram illustrates how a gateway publishes data on behalf of a device that uses Bluetooth for local communication with the gateway.\nThe device establishes a Bluetooth connection with the gateway. The gateway sends an MQTT CONNECT packet to Hono’s MQTT adapter to establish an MQTT connection. The packet contains the gateway’s credentials. The MQTT adapter determines the tenant from the username contained in the CONNECT packet and retrieves the hashed password that is on record for the gateway from the Credentials service. The Credentials service returns the hashed password. The MQTT adapter checks the password and accepts the connection request. The device sends some sensor readings via Bluetooth to the gateway. The gateway forwards the sensor data in an MQTT PUBLISH packet to the MQTT adapter. The topic name contains the identifier of the device that the gateway acts on behalf of. The MQTT adapter invokes the Device Registration service’s assert Device Registration operation to check if the gateway is authorized to act on behalf of the device. The Device Registration service confirms the gateway’s authorization. The MQTT adapter accepts the sensor data from the gateway and forwards it downstream. Note that the device itself is not authenticated by the MQTT adapter in this case. The responsibility for establishing and verifying the device identity lies with the gateway in this setup. It is therefore not necessary to provision credentials for the devices to Hono.\nThe Device Registry Management API’s /devices resource can be used to register gateways and devices. The gateways that are authorized to act on behalf of a device can be set by means of the device’s via and viaGroups properties. This is useful in cases where a device may roam among multiple gateways.\nWhen sending commands to a device, Hono needs to determine which of the authorized gateways should be used to forward the command message to the device. For this purpose, Hono’s protocol adapters keep track of the last known gateway which has acted on behalf of each device by means of the Command Router API.\nGateway Groups In larger deployments with many gateways it can become cumbersome to list all possible gateways in the via property of each device explicitly. This becomes even more of a burden when gateways are added and/or removed frequently. To help with such situations it is possible to define groups of gateways using Hono’s Device Registry Management API.\nA gateway group can be defined implicitly by means of adding the group’s identifier to the list in the memberOf property of a (gateway) device that should belong to the group. The gateway group ID can then be added to the viaGroups property of those devices that all gateways in the gateway group are authorized to act on behalf of.\nNote that the Device Registration API, which is used by protocol adapters to verify if a gateway may act on behalf of a device, has no notion of gateway groups. Thus, the response message of the Device Registration API’s assert Device Registration operation does not contain the IDs of gateway groups in its via property but instead contains the IDs of all (gateway) devices that are a member of any of the authorized gateway groups.\nInfo Hono’s example device registry does not support nested gateway groups.\nConnecting via a Protocol Gateway Hono already comes with a set of standard protocol adapters which support the most widely used (IP based) IoT protocols like HTTP, MQTT and AMQP 1.0. Devices using one of these protocols might be able to directly connect to the corresponding adapter as described in the previous section. However, even if the device supports MQTT it might still not be possible to connect to the MQTT adapter because the device expects to use a topic structure that differs from the one employed by the MQTT adapter. In other cases devices might use a proprietary, highly optimized, binary (IP based) protocol for communication with back end infrastructure.\nHono supports connecting such devices to one of the standard protocol adapters by means of a protocol gateway. A protocol gateway is a software service which translates hence and forth between the device’s proprietary protocol and the protocol used by the Hono protocol adapter. This concept is very similar to the device gateway described above. The main difference is that a protocol gateway is usually deployed in the back end (close to the protocol adapter) whereas a device gateway is usually deployed close to the devices that are connected to the gateway using a mechanism that is usually constrained to a local area.\nThe diagram below illustrates how two devices use a proprietary IP based protocol to connect to a protocol gateway in the back end which in turn is connected to Hono’s standard AMQP 1.0 protocol adapter.\nThe devices publish data to the protocol gateway using the proprietary IP based protocol. The gateway then puts the data into AMQP 1.0 messages and forwards them to the Hono AMQP adapter using the AMQP 1.0 protocol.\nThe requirements and prerequisites for this approach are the same as those for the standard device gateway scenario. Authentication and authorization of gateways works in the same way.\nGeneric MQTT Protocol Gateway Template The repository hono-extras contains a generic template for an MQTT protocol gateway. This template allows you to develop a production-ready protocol gateway with minimal effort, with which you can connect existing MQTT-enabled devices to Hono. For example, you can use other topic names or structures, or you can transform, enrich, compress, or encrypt the payload.\nExample Code Hono’s examples module contains code for a simple protocol gateway illustrating how devices using a binary TCP based protocol can be connected to Hono’s AMQP adapter.\n",
    "description": "",
    "tags": null,
    "title": "Connecting Devices",
    "uri": "/hono/docs/2.7/concepts/connecting-devices/"
  },
  {
    "content": "Business Applications need to know when an attempt to send a command to device is feasible, e.g. because the device is then known to be connected to a protocol adapter. Devices and Protocol Adapters can indicate to Business Applications a device’s intent to receive commands using specific notifications.\nTime until Disconnect Notification Devices and Protocol Adapters can notify an application about the fact that a device is connected and ready to receive one or more commands by means of including a time till disconnect (ttd) property in telemetry or event messages.\nThe ttd property value indicates the amount of time (in seconds) that the device will stay connected to the protocol adapter. Using this value together with the creation-time of the message, an application can determine whether an attempt to send a command to the device has a reasonable chance of succeeding. The ttd property can be included in any regular telemetry or event message. However, if a device does not have any telemetry data or event to upload to the adapter, it can also use an empty notification instead.\nHono includes utility classes that application developers can use to register a callback to be notified when a device sends a ttd notification. See Hono’s example module for details where such a notification callback is used. Please refer to the Telemetry API and the Event API for further details.\nThe following table defines the possible values of the ttd property and their semantics:\nTTD Description \u003e 0 The value indicates the number of seconds that the device will stay connected. Devices using a stateless protocol like HTTP will be able to receive a single command only before disconnecting. -1 The device is now connected (i.e. available to receive upstream messages) until further notice. 0 The device is now disconnected (i.e. not available anymore to receive upstream messages). Determining a Device’s Connection Status An application receiving a downstream message containing a ttd property can check if the device is currently connected (and thus ready to receive a command) by\nadding the ttd value to the creation-time to determine the expiration time, and then comparing the current time with the expiration time If the current time is after the expiration time, the device should be assumed to already have disconnected again.\nSource of the ttd Value While it seems to be natural that a device itself indicates when it is ready to receive a command, it may not always be possible or desirable to do so. A device could e.g. be not capable to specify the value for ttd in its message, or all devices of a particular setup would always use the same value for ttd, so it would not make much sense to provide this value with each request. Additionally, different protocols may not allow the sender to set specific values for a message, so a device using a specific protocol may not be able to provide a value for the ttd property at all. For these reasons there are additional ways of specifying the ttd:\nHono’s Tenant and Device Registration APIs support the inclusion of default values for application-properties in the AMQP 1.0 message. This way, a device can be configured to always have a specific value for ttd set in messages originating from the device. In a future extension there may be a configuration value per tenant and protocol adapter that sets the value of ttd if it was not provided by other means already (like provided to the protocol adapter or by setting a default value). CoAP protocol adapter Hono’s CoAP protocol adapter supports the setting of the ttd value in requests explicitly. Please refer to the CoAP Adapter user guide for details. Alternatively, a default ttd property value can be specified for devices as mentioned above.\nHTTP protocol adapter Hono’s HTTP protocol adapter supports the setting of the ttd value in requests explicitly. Please refer to the HTTP Adapter user guide for details. Alternatively, a default ttd property value can be specified for devices as mentioned above.\nThe following sequence diagram shows a Time till disconnect notification while sending a telemetry message downstream via the HTTP protocol adapter:\nDevice command readiness with telemetry data The following sequence diagram shows a Time till disconnect notification by sending an empty event message downstream via the HTTP protocol adapter:\nDevice command readiness with explicit event AMQP protocol adapter The AMQP protocol adapter automatically initiates sending a Time till disconnect notification via the Command Router with a ttd value of -1 for a device that opens a receiver link for the command source address. Please refer to the AMQP Adapter user guide for details.\nWhen a device closes the receiver link again, the adapter automatically initiates a Time until disconnect notification via the Command Router with a ttd value of 0.\nMQTT protocol adapter The MQTT protocol adapter automatically initiates sending a Time till disconnect notification via the Command Router with a ttd value of -1 for a device that subscribes to the appropriate command topic. Please refer to the MQTT Adapter user guide for details.\nWhen a device unsubscribes again, the adapter automatically initiates a Time till disconnect notification via the Command Router with a ttd value of 0.\n",
    "description": "",
    "tags": null,
    "title": "Device Notifications",
    "uri": "/hono/docs/2.7/concepts/device-notifications/"
  },
  {
    "content": "Business applications can send commands to devices by means of the Command \u0026 Control API. This concept page describes how this API is used by applications to send commands and describes how Hono’s protocol adapters process the commands so that they reach their target device.\nCommands can be sent following a request/response or a one-way pattern. For Request/Response commands, there is always a response expected from the device.\nGeneral concept In order for devices to be able to receive commands, they first have to connect to a Hono protocol adapter and indicate their availability to receive commands. For devices communicating via AMQP or MQTT, this means connecting to an adapter and explicitly subscribing for commands. For devices sending messages via HTTP or CoAP, this means using the ttd (time till disconnect) parameter when sending an event or telemetry message, thereby indicating for how long the device will wait for a command message.\nThe protocol adapter will then forward a notification to downstream business applications about the device being able to receive commands and for how long.\nAn application can send a command to such a device via the used messaging infrastructure. Hono will receive the command by means of the Command Router component and will forward it to the protocol adapter instance that the device is connected to. The protocol adapter will then send the command to the device. In case of a request/response command, the device is expected to send back a command response message.\nWhen the device explicitly ends the command subscription, the protocol adapter will send a corresponding notification to downstream applications.\nCommand \u0026 Control involving a gateway Hono has special support for sending commands to devices that are connected to Hono via a gateway device. The gateways that a device may use to connect to Hono’s protocol adapters need to be configured in Hono’s device registry as part of the device provisioning process.\nWhen sending commands, applications do not need to know to which gateway the command target device is connected to. An application sends the command with the device address and Hono will direct the command to a gateway that has subscribed for such commands and that is configured to act on behalf of the command target device. If there are multiple matching gateways, the one that the command target device was last connected to is chosen. The information about which gateways are subscribed and which gateway a device has last communicated by is managed via the Command Router API.\nMessage flow using AMQP messaging network The following sections and the contained sequence diagrams provide an overview of a device indicating its availability for receiving commands, of an application sending a command to the device and of the device sending back a command response.\nDevice indicating availability to receive commands Command subscription When the Device subscribes for commands (1), the Protocol Adapter registers the command consumer with the Command Router service, associating the device with its protocol adapter instance identifier (2). The Command Router service creates a receiver link scoped to the device’s tenant (3) if it doesn’t exist yet. Following that, the notification about the device subscription is sent to the Application via the AMQP messaging network (4).\nBusiness application sending a command to the device Command handling Upon receiving the notification, the Application prepares sender and command response receiver links (1,2) and sends the command message to the AMQP messaging network. The message is received by the Command Router service component (3), which will determine the Protocol Adapter instance #1 that is able to handle the command message. The command then gets forwarded to the AMQP messaging network on the address for adapter instance #1 (4). The Protocol Adapter instance #1 receives the message (5) and forwards it to the Device (6). As the last step, an accepted disposition will be sent back to the Application (7).\nDevice sending a command response message Command response handling The command response message is sent back to the Application from the Protocol Adapter via the AMQP messaging network. Note that the Command Router is not involved in this transfer.\n",
    "description": "",
    "tags": null,
    "title": "Command \u0026 Control",
    "uri": "/hono/docs/2.7/concepts/command-and-control/"
  },
  {
    "content": "Resource limits such as the maximum number of device connections allowed per tenant or the allowed data volume of the messages over a period of time per tenant can be set in Hono.\nHono specifies an API ResourceLimitChecks that is used by the protocol adapters for the verification of the configured resource limits. A default implementation of this API is shipped with Hono. This default implementation uses the live metrics data retrieved from a Prometheus server to verify the resource-limits, if configured. To enable and use this default implementation, please refer to the protocol adapter admin guides. Based on the requirements, a custom version of the above API can be implemented and used. The resource-limits for a tenant can be set using the tenant configuration. Please refer to the Tenant API for more details.\nConnections Limit Before accepting a new connection request from a device, the number of existing connections is checked against the configured limit by the protocol adapters. The connection request is declined if the limit is exceeded.\nThe MQTT and AMQP protocol adapters keep the connections longer opened than their counterparts such as HTTP. Thereby the MQTT and AMQP adapters are enabled to check the connection limits before accepting any new connection to a device.\nConnection Duration Limit Before accepting a new connection request from a device, the overall amount of time that the devices have already been connected to protocol adapters for that tenant is checked against the configured limit by the protocol adapters. The connection request is declined if the connection duration limit has been already reached. This limit is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric.\nThe default Prometheus based implementation uses connection duration as the factor to limit the connections. This default implementation supports two modes of connection duration limit calculation namely days and monthly. For more details on how to set the mode refer to the Tenant API. If the period is not set explicitly, then the mode is assumed as monthly in the default implementation.\nIn the monthly mode, further device connections are only allowed, if the overall amount of time that the devices have already been connected from the beginning till the end of the current (Gregorian) calendar month does not exceed the configured max-minutes value. But for the first month, on which the connection duration limit became effective, the effective connection duration limit is calculated based on the max-minutes with respect to the remaining days in that month from the effective-since date.\nBelow is a sample resource limit configuration for a tenant, where it has been defined that the connection duration limit became effective on 10.Jul.2019 and the maximum connection duration limit for every month is 50,000 minutes. It means that from August 2019, the connection limit check ensures that no more connections are allowed for that tenant, if that limit of 50,000 minutes is already reached. But in case of July 2019, the month on which the message limit became effective, the effective connection duration limit is calculated by finding the average limit for a day from the configured max-minutes and then multiplying it with the number of days from the effective-since date till the end of that month. In this case it is calculated as (50,000 minutes / 31 days) x 22 days, which is 35,483 minutes. It means that for the month of July 2019, no more new connections are allowed, if the limit of 35,843 minutes is already reached.\n\"resource-limits\": { \"connection-duration\": { \"effective-since\": \"2019-07-10T14:30:00Z\", \"max-minutes\": 50000, \"period\": { \"mode\": \"monthly\" } } } In the days mode, further device connections are only allowed, if the overall amount of time that the devices have already been connected for the configured no-of-days does not exceed the max-minutes value. In the below sample configuration, the mode is configured as days and the accounting duration as 30 days. In this case the connection duration limit check ensures that new connections are accepted, only if the connection duration usage for every 30 days from 10.Jul.2019 (effective-since) does not exceed the 50,000 minutes limit.\n\"resource-limits\": { \"connection-duration\": { \"effective-since\": \"2019-07-10T14:30:00Z\", \"max-minutes\": 50000, \"period\": { \"mode\": \"days\", \"no-of-days\": 30 } } } Messages Limit Hono supports limiting the number of messages that devices and north bound applications of a tenant can publish to Hono during a given time interval. Before accepting any telemetry or event or command messages from devices or north bound applications, it is checked by the protocol adapters that if the message limit is exceeded or not. The incoming message is discarded if the limit is exceeded.\nThe default Prometheus based implementation uses data volume as the factor to limit the messages. The data volume already consumed by a tenant over the given time interval is compared with the configured message limit before accepting any messages. The default implementation supports two modes of message limits calculation namely days and monthly. For more details on how to set the mode refer to the Tenant API. If the period is not set explicitly, then the mode is assumed as monthly in the default implementation.\nIn the monthly mode, the message limit check ensures that the data usage from the beginning till the end of a (Gregorian) calendar month does not exceed the max-bytes value. But for the first month on which the message limit became effective, the effective max-bytes are calculated based on the max-bytes with respect to the remaining days in that month from the effective-since date.\nBelow is a sample resource limit configuration for a tenant and it has been defined that the message limit became effective on 10.Jul.2019 and the maximum bytes allowed for a month is 2 GB. It means that from August 2019, the message limit check ensures that the data usage in a month does not exceed 2 GB. But in case of July 2019, the month on which the message limit became effective, the effective max-bytes is calculated by finding the average limit for a day from the max-bytes and multiplying it with the number of days from the effective-since date till the end of that month. In this case it is calculated as (2 GB / 31 days) x 22 days which is 1.4 GB. It means that for the month of July 2019, the data usage should not exceed 1.4GB.\n\"resource-limits\": { \"data-volume\": { \"effective-since\": \"2019-07-10T14:30:00Z\", \"max-bytes\": 2147483648, \"period\": { \"mode\": \"monthly\" } } } In the days mode, the message limit check ensures that the data usage for the defined no-of-days does not exceed the max-bytes value. In the below sample configuration, the mode is configured as days and the accounting duration as 30 days. In this case the message limit check ensures that the data usage for every 30 days from 10.Jul.2019 (effective-since) does not exceed the 2GB limit.\n\"resource-limits\": { \"data-volume\": { \"effective-since\": \"2019-07-10T14:30:00Z\", \"max-bytes\": 2147483648, \"period\": { \"mode\": \"days\", \"no-of-days\": 30 } } } ",
    "description": "",
    "tags": null,
    "title": "Resource limits",
    "uri": "/hono/docs/2.7/concepts/resource-limits/"
  },
  {
    "content": "Hono’s protocol adapters can use connection events to indicate the connection status of a device. In particular, an adapter can notify downstream components about a newly established connection with a device or about a device having disconnected.\nThe connection status of devices using stateful protocols like MQTT and AMQP can usually be determined quite easily because these protocols often require peers to explicitly open or close a connection and often also support a kind of heart beat which can be used to determine if a connection is still alive. However, for stateless protocols like HTTP or CoAP, there is no clear definition of what it actually means that a device is connected. It is obvious that a device is connected when it is sending an HTTP request. However, the adapter has no way of knowing if the device has gone to sleep after it has received the adapter’s response to its request.\nThat said, connection events indicating an established connection with a device can usually be taken as face value. However, connection events indicating the disconnection of a device may only represent the protocol adapters view of the device’s connection status. For example, the HTTP adapter might consider a device disconnected because it hasn’t received any requests from the device for some time. However, the device itself might as well be up and running (i.e. not sleeping) and simply have no data worth publishing.\nThe mechanism of firing connection events is pluggable with the default implementation simply forwarding connection status information to the logging framework. Hono also comes with an alternative implementation which forwards connection status information by means of Connection Events via the Events API.\n",
    "description": "",
    "tags": null,
    "title": "Connection Events",
    "uri": "/hono/docs/2.7/concepts/connection-events/"
  },
  {
    "content": "User Guide Learn how Eclipse Hono™ enables you to quickly send data from devices to business applications and vice versa.\n",
    "description": "",
    "tags": null,
    "title": "User Guide",
    "uri": "/hono/docs/2.7/user-guide/"
  },
  {
    "content": "The Device Registry component provides implementations of Hono’s Tenant API, Device Registration API and Credentials API. Protocol adapters use these AMQP 1.0 based APIs to determine a device’s registration status during runtime. For example, when a device tries to connect to a protocol adapter, the adapter uses information retrieved from the device registry to check if the device is enabled, whether the tenant that it belongs to requires devices to authenticate before accepting any data from it and if so, for verifying the device’s credentials.\nIn addition to the above APIs, the Device Registry also exposes HTTP endpoints for managing the content of the registry according to the Device Registry Management API. This API is used by administrators to create and configure tenants and provision devices into the system. Without these steps, no devices can connect to any of Hono’s protocol adapters. The Device Provisioning concept page describes the steps necessary to manually provision a device and also provides information about how devices can be provisioned automatically based on X.509 client certificates.\nHono comes with two registry implementations out of the box:\nThe Mongo DB based registry persists data to collections of a Mongo DB. The JDBC based registry persists data to tables of a relational database. Please refer to the corresponding Admin Guides for details regarding the configuration of the registries.\nTip During runtime, the protocol adapters require access to any implementation of the Tenant, Device Registration and Credentials APIs. However, they do not require these implementations to be the Mongo DB or the JDBC based registry coming with Hono. This means that the protocol adapters can also be configured to access custom implementations of these APIs which, for example, serve as a facade for an existing application or service that contains the relevant device data.\nDevice Registry Management API The HTTP based Device Registry Management API can be used by administrators and/or applications to create, update and delete the entities managed by the registry. This includes tenants, the devices belonging to the tenants and the credentials that devices use to authenticate to protocol adapters.\nAuthentication The registry implementations can be configured to require clients of the management API to authenticate using the standard HTTP basic authentication mechanism. For more information on how to configure authentication, please refer to the registry’s corresponding Admin Guide.\nManaging Tenants The tenants in the registry can be managed using the Device Registry Management API’s tenant related resources.\nInfo The JDBC based registry implementation currently has the following limitations:\nTenants can be retrieved using the search tenants operation defined by the Device Registry Management API, but the filterJson and sortJson query parameters are (currently) being ignored. The result set will always be sorted by the tenant ID in ascending order. The alias and trust-anchor-group properties defined on a tenant are being ignored by the registry. Consequently, multiple tenants can not be configured to use the same trust anchor(s). Registering a Certificate Authority Devices can use an X.509 client certificate for authenticating to Hono’s protocol adapters. In order for this to work, one or more root certificate authorities (CAs) need to be registered with the tenant that the devices belong to.\nThe Management API can be used to register CAs based on a public key plus some meta data. It also supports registering CAs using PEM files that contain a signed certificate.\nGiven a certificate in a PEM file (i.e. one that begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----), the Base64 string representing the certificate’s binary encoding can be extracted from the file using the following command:\nCERT=$(openssl x509 -in my-ca-cert.pem -outform PEM | sed /^---/d | sed -z 's/\\n//g') The CA can then be registered using the Management API:\nTENANT_ID=my-tenant REGISTRY_IP=hono.eclipseprojects.io curl --location 'https://${REGISTRY_IP}:28443/v1/tenants/${TENANT_ID}' --header 'content-type: application/json' --data '{ \"trusted-ca\": [ { \"cert\": \"'${CERT}'\" } ], \"ext\": { \"messaging-type\": \"kafka\" } }' The TENANT_ID and REGISTRY_IP variables need to be adapted to the Hono installation and tenant being used.\nRegistration Limits The registry implementations support the enforcement of registration limits defined at the tenant level. In particular, the registries enforce\nthe maximum number of devices that can be registered for each tenant and the maximum number of credentials that can be registered for each device of a tenant. In order to enable enforcement of any of these limits for a tenant, the corresponding registration-limits property needs to be set explicitly on the tenant like in the example below:\n{ \"registration-limits\": { \"max-devices\": 100, \"max-credentials-per-device\": 5 } } The registry implementations can also be configured with a global limit for the number of devices that can be registered per tenant. The value can be set via the registry’s HONO_REGISTRY_SVC_MAXDEVICESPERTENANT configuration variable. The maximum number of devices allowed for a particular tenant is then determined as follows:\nIf the tenant’s registration-limits/max-devices property has a value \u003e -1 then that value is used as the limit. Otherwise, if the HONO_REGISTRY_SVC_MAXDEVICESPERTENANT configuration variable has a value \u003e -1 then that value is used as the limit. Otherwise, the number of devices is unlimited. Managing Devices The devices in the registry can be managed using the Device Registry Management API’s device related resources.\nInfo The JDBC based registry implementation currently has the following limitations:\nRegistration information can be retrieved using the search devices operation defined by the Device Registry Management API. The filterJson query parameter currently only allows one filter expression per request, the sortJson query parameter is (currently) being ignored. The result set will always be sorted by the device ID in ascending order. Managing Credentials The device’s credentials can be managed using the Device Registry Management API’s credentials related resources.\n",
    "description": "",
    "tags": null,
    "title": "Device Registry",
    "uri": "/hono/docs/2.7/user-guide/device-registry/"
  },
  {
    "content": "The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nDevice Authentication The HTTP adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. The adapter supports both the Basic HTTP authentication scheme as well as client certificate based authentication as part of a TLS handshake for that purpose.\nThe adapter tries to authenticate the device using these mechanisms in the following order\nClient Certificate The HTTP adapter supports authenticating clients based on TLS cipher suites using a digital signature based key exchange algorithm as described in RFC 5246 (TLS 1.2) and RFC 8446 (TLS 1.3). This requires a client to provide an X.509 certificate containing a public key that can be used for digital signature. The adapter uses the information in the client certificate to verify the device’s identity as described in Client Certificate based Authentication.\nInfo The HTTP adapter needs to be configured for TLS in order to support this mechanism.\nHTTP Basic Auth The HTTP adapter supports authenticating clients using the Basic HTTP authentication scheme. This means that clients need to provide a user-id and a password encoded in the authorization HTTP request header as defined in RFC 7617, Section 2 when connecting to the HTTP adapter. The user-id component of the header value must match the pattern auth-id@tenant, e.g. sensor1@DEFAULT_TENANT.\nThe adapter extracts the auth-id, tenant and password from the request header and verifies them using the credentials that the configured Credentials service has on record for the client as described in Username/Password based Authentication. If the credentials match, the client has been authenticated successfully and the request is being processed.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nHTTP Bearer Auth The HTTP adapter supports authenticating clients using the Bearer HTTP authentication scheme. This requires a client to provide a signed JSON Web Token (JWT) as a Bearer token inside the authentication header. The information about the tenant and the authentication identifier can be presented to the protocol adapter in one of two ways:\nEither as claims inside the JSON Web Signature (JWS) payload. For more information on this see JSON Web Token based Authentication or inside the URI, in which case the URI must have the format for unauthenticated device even for authenticated devices (see Publish Telemetry Data (unauthenticated Device). The adapter extracts the auth-id, tenant and JWT from the HTTP request and verifies them using the credentials that the configured Credentials service has on record for the client as described in JSON Web Token based Authentication. If the JWT is verified in combination with the credentials and within its validity period, the client has been authenticated successfully and the connection is being established. The validity period is defined within the JWS payload by the mandatory claims iat (“issued at”) and exp (“expiration time”). Please refer to JSON Web Token based Authentication for more detailed information.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nMessage Limits The adapter rejects\na client’s request to upload data with status code 429 Too Many Requests and any AMQP 1.0 message containing a command sent by a north bound application if the message limit that has been configured for the device’s tenant is exceeded.\nPublish Telemetry Data (authenticated Device) URI: /telemetry Method: POST Request Headers: (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) qos-level: The QoS level for publishing telemetry messages. The adapter supports at most once (0) and at least once (1) QoS levels. The default value of 0 is assumed if this header is omitted. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute. 202 (Accepted): The telemetry data has been accepted for processing. Note that if the qos-level request header is omitted (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer. However, if the QoS level header is set to 1 (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. The qos-level header value is invalid. 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the QoS level header is set to 1 (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExamples\nPublish some JSON data for device 4711:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data for device 4711 using at least once QoS:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry HTTP/1.1 200 OK hono-command: set hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92 content-length: 23 { \"brightness\": 87 } Publish some JSON data for device 4711 using a client certificate for authentication:\n# in base directory of Hono repository: curl -i --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cacert demo-certs/certs/trusted-certs.pem -H 'content-type: application/json' --data-binary '{\"temp\": 5}' https://hono.eclipseprojects.io:8443/telemetry HTTP/1.1 202 Accepted content-length: 0 Info The example above assumes that the HTTP adapter is configured for TLS and the secure port is used.\nPublish Telemetry Data (unauthenticated Device) URI: /telemetry/${tenantId}/${deviceId} Method: PUT Request Headers: (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) qos-level: The QoS level for publishing telemetry messages. The adapter supports at most once (0) and at least once (1) QoS levels. The default value of 0 is assumed if this header is omitted. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute. 202 (Accepted): The telemetry data has been accepted for processing. Note that if the qos-level request header is omitted (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer. However, if the QoS level header is set to 1 (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. The qos-level header value is invalid. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the QoS level header is set to 1 (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the HONO_HTTP_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nPublish some JSON data for device 4711:\ncurl -i -X PUT -H 'content-type: application/json' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry/DEFAULT_TENANT/4711 HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data for device 4711 using at least once QoS:\ncurl -i -X PUT -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry/DEFAULT_TENANT/4711 HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncurl -i -X PUT -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry/DEFAULT_TENANT/4711 HTTP/1.1 200 OK hono-command: set hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92 content-length: 23 { \"brightness\": 87 } Publish Telemetry Data (authenticated Gateway) URI: /telemetry/${tenantId}/${deviceId} or /telemetry//${deviceId} Method: PUT Request Headers: (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) qos-level: The QoS level for publishing telemetry messages. The adapter supports at most once (0) and at least once (1) QoS levels. The default value of 0 is assumed if this header is omitted. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute. 202 (Accepted): The telemetry data has been accepted for processing. Note that if the qos-level request header is omitted (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer. However, if the QoS level header is set to 1 (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. The qos-level header value is invalid. 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The tenant that the gateway belongs to is not allowed to use this protocol adapter. The device belongs to another tenant than the gateway. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the QoS level header is set to 1 (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This resource can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data on behalf of device 4712:\ncurl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry//4712 HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data on behalf of device 4712 using at least once QoS:\ncurl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry//4712 HTTP/1.1 202 Accepted content-length: 0 Publish some JSON data on behalf of device 4712, indicating that the gateway will wait for 10 seconds to receive the response:\ncurl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry//4712 HTTP/1.1 200 OK hono-command: set hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92 content-length: 23 { \"brightness\": 87 } Info The example above assumes that a gateway device has been registered with hashed-password credentials with auth-id gw and password gw-secret which is authorized to publish data on behalf of device 4712.\nPublish an Event (authenticated Device) URI: /event Method: POST Request Headers: (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) hono-ttl: The message’s time-to-live in number of seconds. Alternatively, this may be specified using a URI query parameter of the same name. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The event has been accepted for processing. The response contains a command for the device to execute. 202 (Accepted): The event has been accepted for processing. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This is the preferred way for devices to publish events. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExample\nPublish some JSON data for device 4711:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{\"alarm\": true}' http://hono.eclipseprojects.io:8080/event HTTP/1.1 202 Accepted content-length: 0 Publish an Event (unauthenticated Device) URI: /event/${tenantId}/${deviceId} Method: PUT Request Headers: (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) hono-ttl: The message’s time-to-live in number of seconds. Alternatively, this may be specified using a URI query parameter of the same name. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The event has been accepted and put to a persistent store for delivery to consumers. The response contains a command for the device to execute. 202 (Accepted): The event has been accepted and put to a persistent store for delivery to consumers. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the HONO_HTTP_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nPublish some JSON data for device 4711:\ncurl -i -X PUT -H 'content-type: application/json' --data-binary '{\"alarm\": true}' http://hono.eclipseprojects.io:8080/event/DEFAULT_TENANT/4711 HTTP/1.1 202 Accepted content-length: 0 Publish an Event (authenticated Gateway) URI: /event/${tenantId}/${deviceId} or /event//${deviceId} Method: PUT Request Headers: (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: The type of payload contained in the request body. Required, if the request body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttd: The number of seconds the device will wait for the response. Alternatively, this may be specified using a URI query parameter of the same name. (optional) hono-ttl: The message’s time-to-live in number of seconds. Alternatively, this may be specified using a URI query parameter of the same name. Request Body: (optional) Arbitrary payload matching the given content type. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data or if the request failed and the response body contains error details. (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device. (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200. (optional) Error details, if status code is \u003e= 400. Status Codes: 200 (OK): The event has been accepted and put to a persistent store for delivery to consumers. The response contains a command for the device to execute. 202 (Accepted): The event has been accepted and put to a persistent store for delivery to consumers. 400 (Bad Request): The request cannot be processed. Possible reasons for this include: The request body is empty and the content-type header is missing. The content-type header indicates an empty-notification but the request body is not empty. 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The tenant that the gateway belongs to is not allowed to use this protocol adapter. The device belongs to another tenant than the gateway. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This resource can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data on behalf of device 4712:\ncurl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/event//4712 HTTP/1.1 202 Accepted content-length: 0 Info The example above assumes that a gateway device has been registered with hashed-password credentials with auth-id gw and password gw-secret which is authorized to publish data on behalf of device 4712.\nCommand \u0026 Control The HTTP adapter enables devices to receive commands that have been sent by business applications. Commands are delivered to the device by means of an HTTP response message. That means a device first has to send a request, indicating how long it will wait for the response. That request can either be a telemetry or event message, with a hono-ttd header or query parameter (ttd for time till disconnect) specifying the number of seconds the device will wait for the response. The business application can react on that message by sending a command message, targeted at the device. The HTTP adapter will then send the command message as part of the HTTP response message with status 200 (OK) to the device. If the HTTP adapter receives no command message in the given time period, a 202 (Accepted) response will be sent to the device (provided the request was valid).\nSpecifying the Time a Device will wait for a Response The adapter lets devices indicate the number of seconds they will wait for a response by setting a header or a query parameter.\nHeader Query Parameter The (optional) hono-ttd header can be set in requests for publishing telemetry data or events:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'hono-ttd: 60' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry HTTP/1.1 202 Accepted content-length: 0 The (optional) hono-ttd query parameter can be used in requests for publishing telemetry data or events:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{\"temp\": 5}' http://hono.eclipseprojects.io:8080/telemetry?hono-ttd=60 HTTP/1.1 202 Accepted content-length: 0 Commands handled by gateways Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See Connecting via a Device Gateway for details.\nA gateway can send a request with the hono-ttd header or query parameter on the /event or /telemetry URI, indicating its readiness to receive a command for any device it acts on behalf of. Note that in this case, the business application will be notified with the gateway id in the device_id property of the downstream message.\nAn authenticated gateway can also indicate its readiness to receive a command targeted at a specific device. For that, the /event/${tenantId}/${deviceId} or /telemetry/${tenantId}/${deviceId} URI is to be used, containing the id of the device to receive a command for. The business application will receive a notification with that device id.\nIf there are multiple concurrent requests with a hono-ttd header or query parameter, sent by the command target device and/or one or more of its potential gateways, the HTTP adapter will choose the device or gateway to send the command to as follows:\nA request done by the command target device or by a gateway specifically done for that device, has precedence. If there are multiple, concurrent such requests, the last one will get the command message (if received) in its response. Note that the other requests won’t be answered with a command message in their response event if the business application sent multiple command messages. That means commands for a single device can only be requested sequentially, not in parallel. If the above doesn’t apply, a single hono-ttd request on the /event or /telemetry URI, sent by a gateway that the command target device is configured for, will get the command message in its response. If there are multiple, concurrent such requests by different gateways, all configured for the command target device, the request by the gateway will be chosen, through which the target device has last sent a telemetry or event message. If the target device hasn’t sent a message yet and it is thereby unknown via which gateway the device communicates, then one of the requests will be chosen randomly to set the command in its response. Sending a Response to a Command (authenticated Device) URI: /command/res/${commandRequestId} or /command/res/${commandRequestId}?hono-cmd-status=${status} Method: POST Request Headers: (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This header may be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body. (optional) hono-cmd-status: The status of the command execution. If not set, the adapter expects that the URI contains it as a query parameter. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the request failed and the response body contains error details. Response Body: (optional) Error details, if status code is \u003e= 400. Status Codes: 202 (Accepted): The response has been successfully delivered to the application that has sent the command. 400 (Bad Request): The request cannot be processed because the command status is missing. 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This is the preferred way for devices to respond to commands. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExample\nSend a response to a previously received command with the command-request-id req-id-uuid for device 4711:\ncurl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{\"brightness-changed\": true}' http://hono.eclipseprojects.io:8080/command/res/req-id-uuid?hono-cmd-status=200 HTTP/1.1 202 Accepted content-length: 0 Sending a Response to a Command (unauthenticated Device) URI: /command/res/${tenantId}/${deviceId}/${commandRequestId} or /command/res/${tenantId}/${deviceId}/${commandRequestId}?hono-cmd-status=${status} Method: PUT Request Headers: (optional) content-type: A media type describing the semantics and format of the payload contained in the request body (the outcome of processing the command). (optional) hono-cmd-status: The status of the command execution. If not set, the adapter expects that the URI contains it as a query parameter. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the request failed and the response body contains error details. Response Body: (optional) Error details, if status code is \u003e= 400. Status Codes: 202 (Accepted): The response has been successfully delivered to the application that has sent the command. 400 (Bad Request): The request cannot be processed because the command status is missing. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this might be: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the HONO_HTTP_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nSend a response to a previously received command with the command-request-id req-id-uuid for the unauthenticated device 4711:\ncurl -i -X PUT -H 'content-type: application/json' --data-binary '{\"brightness-changed\": true}' http://hono.eclipseprojects.io:8080/command/res/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status=200 HTTP/1.1 202 Accepted content-length: 0 Sending a Response to a Command (authenticated Gateway) URI: /command/res/${tenantId}/${deviceId}/${commandRequestId} or /command/res/${tenantId}/${deviceId}/${commandRequestId}?hono-cmd-status=${status} or /command/res//${deviceId}/${commandRequestId} or /command/res//${deviceId}/${commandRequestId}?hono-cmd-status=${status} Method: PUT Request Headers: (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment. (optional) content-type: A media type describing the semantics and format of the payload contained in the request body (the outcome of processing the command). (optional) hono-cmd-status: The status of the command execution. If not set, the adapter expects that the URI contains it as a query parameter. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Headers: (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the request failed and the response body contains error details. Response Body: (optional) Error details, if status code is \u003e= 400. Status Codes: 202 (Accepted): The response has been successfully delivered to the application that has sent the command. 400 (Bad Request): The request cannot be processed because the command status is missing. 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this might be: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 404 (Not Found): The request cannot be processed because the device is disabled or does not exist. 413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This resource can be used by gateway components to send the response to a command on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to send responses to a command on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nSend a response to a previously received command with the command-request-id req-id-uuid on behalf of device 4712:\ncurl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{\"brightness-changed\": true}' http://hono.eclipseprojects.io:8080/command/res//4712/req-id-uuid?hono-cmd-status=200 HTTP/1.1 202 Accepted content-length: 0 Info The example above assumes that a gateway device has been registered with hashed-password credentials with auth-id gw and password gw-secret which is authorized to publish data on behalf of device 4712.\nDownstream Meta Data The adapter includes the following meta data in messages being sent downstream:\nName Type Description orig_adapter string Contains the adapter’s type name which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The HTTP adapter’s type name is hono-http. orig_address string Contains the (relative) URI that the device has originally posted the data to. ttd integer Contains the effective number of seconds that the device will wait for a response. This property is only set if the HTTP request contains the hono-ttd header or request parameter. The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:\nIf the message already contains a non-empty property of the same name, its value remains unchanged. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used. Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.\nEvent Message Time-to-live Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.\nIn most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.\nIn order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the default ttl and max-ttl values configured for a tenant/device as described in the Tenant API.\nTenant specific Configuration The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-http. The following properties are (currently) supported:\nName Type Default Value Description enabled boolean true If set to false the adapter will reject all data from devices belonging to the tenant. max-ttd integer 60 Defines a tenant specific upper limit for the time until disconnect property that devices may include in requests for uploading telemetry data or events. Please refer to the Command \u0026 Control concept page for a discussion of this parameter’s purpose and usage.\nThis property can be set for the hono-http adapter type as an extension property in the adapter section of the tenant configuration.\nIf it is not set, then the default value of 60 seconds is used. Note that in order to use a higher value than the default here, the hono.http.idleTimeout HTTP Adapter configuration property has to be set to a higher value, as the effective time until disconnect value is limited to at most 80 % of the idleTimeout. ",
    "description": "",
    "tags": null,
    "title": "HTTP Adapter",
    "uri": "/hono/docs/2.7/user-guide/http-adapter/"
  },
  {
    "content": "The MQTT protocol adapter exposes an MQTT topic hierarchy for publishing telemetry data and events to downstream consumers and for receiving commands from applications and sending back responses.\nThe MQTT adapter is not a general purpose MQTT broker. In particular the adapter\nsupports clients connecting using MQTT 3.1.1 or 5.0 only. does not maintain session state for clients and thus always sets the session present flag in its CONNACK packet to 0, regardless of the value of the clean session flag provided in a client’s CONNECT packet. ignores any Will included in a client’s CONNECT packet. only supports topic names/filters for devices to publish and subscribe to that are specific to Hono’s functionality as described in the following sections. does not support retaining messages. However, if an event or telemetry message’s retain flag is set to 1 then the corresponding AMQP 1.0 message being sent downstream by the adapter will contain an x-opt-retain message annotation containing the boolean value true. A downstream consumer may then react according to the presence of this annotation. Authentication The MQTT adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. The adapter supports both authentication based on the username/password provided in an MQTT CONNECT packet as well as client certificate based authentication as part of a TLS handshake for that purpose.\nThe adapter tries to authenticate the device using these mechanisms in the following order\nClient Certificate The MQTT adapter supports authenticating clients based on TLS cipher suites using a digital signature based key exchange algorithm as described in RFC 5246 (TLS 1.2) and RFC 8446 (TLS 1.3). This requires a client to provide an X.509 certificate containing a public key that can be used for digital signature. The adapter uses the information in the client certificate to verify the device’s identity as described in Client Certificate based Authentication.\nInfo The adapter needs to be configured for TLS in order to support this mechanism.\nUsername/Password The MQTT adapter supports authenticating clients based on credentials provided during MQTT connection establishment. This means that clients need to provide a user and a password field in their MQTT CONNECT packet as defined in MQTT Version 3.1.1, Section 3.1.3 and MQTT Version 5.0, Section 3.1.3 when connecting to the MQTT adapter. The username provided in the user field must match the pattern auth-id@tenant, e.g. sensor1@DEFAULT_TENANT.\nThe adapter extracts the auth-id, tenant and password from the CONNECT packet and verifies them using the credentials that the configured Credentials service has on record for the client as described in Username/Password based Authentication. If the credentials match, the client has been authenticated successfully and the connection is being established.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nJSON Web Token The MQTT adapter supports authenticating clients based on a signed JSON Web Token (JWT) provided during MQTT connection establishment. This requires a client to provide a client identifier, a user and a password field in its MQTT CONNECT packet as defined in MQTT Version 3.1.1, Section 3.1.3 and MQTT Version 5.0, Section 3.1.3 when connecting to the MQTT adapter. The JWT must be sent in the password field. The content of the user field is ignored. The information about the tenant and the authentication identifier can be presented to the protocol adapter in one of two ways:\nEither as claims inside the JSON Web Signature (JWS) payload. For more information on this see JSON Web Token based Authentication\nor inside the client identifier, in which case the client identifier must have the following format:\n*/${tenant-id}/[^/]*/${auth-id}\nFor example, a client that belongs to tenant example-tenant and for which rpk (raw public key) credentials with an auth-id of device-1 have been registered, might present a client identifier of tenants/example-tenant/devices/device-1 when authenticating to the protocol adapter.\nThe adapter extracts the auth-id, tenant and JWT from the CONNECT packet and verifies them using the credentials that the configured Credentials service has on record for the client as described in JSON Web Token based Authentication. If the JWT is verified in combination with the credentials and within its validity period, the client has been authenticated successfully and the connection is being established. The validity period is defined within the JWS payload by the mandatory claims iat (“issued at”) and exp (“expiration time”). Please refer to JSON Web Token based Authentication for more detailed information.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nResource Limit Checks The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.\nConnection Limits The adapter rejects a client’s attempt to connect using\nMQTT 3.1.1 with return code 0x03 (Server Unavailable), MQTT 5.0 with reason code 0x9C (Use Another Server), if the maximum number of connections per protocol adapter instance is reached.\nThe adapter rejects a client’s attempt to connect using\nMQTT 3.1.1 with return code 0x05 (Not Authorized), MQTT 5.0 with reason code 0x97 (Quota Exceeded), if the maximum number of simultaneously connected devices for the tenant is reached.\nConnection Duration Limits The adapter rejects a client’s attempt to connect using\nMQTT 3.1.1 with return code 0x05 (Not Authorized) MQTT 5.0 with reason code 0x97 (Quota Exceeded) if the connection duration limit that has been configured for the client’s tenant is exceeded.\nMessage Limits The adapter\nrejects a client’s attempt to connect using MQTT 3.1.1 with return code 0x05 (Not Authorized), rejects a client’s attempt to connect using MQTT 5.0 with reason code 0x97 (Quota Exceeded), discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and rejects any command messages sent by a north bound application if the message limit that has been configured for the device’s tenant is exceeded.\nConnection Events The adapter can emit Connection Events for client connections being established and/or terminated. Please refer to the common configuration options for details regarding how to enable this behavior.\nThe adapter includes the client identifier from the client’s MQTT CONNECT packet as the Connection Event’s remote-id.\nPublishing Telemetry Data The MQTT adapter supports the publishing of telemetry data by means of MQTT PUBLISH packets using either QoS 0 or QoS 1. Using QoS 1 will result in the adapter sending an MQTT PUBACK packet to the client once the message has been accepted by the downstream messaging infrastructure.\nThis requires that\nthe messages published by the client comply with the format defined by the Telemetry API and the downstream messaging infrastructure has capacity to process telemetry messages for the client’s tenant. The protocol adapter checks the configured message limit before accepting any telemetry messages. An exceeded message limit will cause an error.\nAny kind of error when processing an incoming telemetry message will be reported back to the client if the client has subscribed on a dedicated error topic. See Error Reporting via Error Topic for details.\nIf such an error subscription by the client exists, the error will by default be ignored after it got published on the error topic, otherwise the connection to the client will be closed. The handling of errors can further be controlled by means of an on-error property bag parameter set on the telemetry message topic. Refer to Error Handling for details.\nAdding Meta Data Devices can add arbitrary meta data to a message by means of a property bag. The property bag is an optional collection of key/value pairs intended for the receiver of the message. The property bag is appended to the end of the topic name. It always starts with a /? character, followed by pairs of URL encoded property names and values that are separated by the \u0026 character.\nThe MQTT adapter currently only supports the content-type property for publishing telemetry data which can be used by devices to indicate the type of data contained in a message. For example, the following topic name can be used to indicate that the message contains a JSON string: /topic/name/?content-type=application%2Fjson.\nPublish Telemetry Data (authenticated Device) Topic: t telemetry Authentication: required Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default). When using this topic, the MQTT adapter determines the device’s tenant and device identity as part of the authentication process.\nExample\nPublish some JSON data for device 4711:\nmosquitto_pub -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t t -m '{\"temp\": 5}' Publish some JSON data for device 4711 using a client certificate for authentication:\n# in base directory of Hono repository: mosquitto_pub -h hono.eclipseprojects.io -p 8883 --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cafile demo-certs/certs/trusted-certs.pem -t t -m '{\"temp\": 5}' Info The example above assumes that the MQTT adapter is configured for TLS and the secure port is used.\nPublish Telemetry Data (unauthenticated Device) Topic: t/${tenant-id}/${device-id} telemetry/${tenant-id}/${device-id} Authentication: none Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the HONO_MQTT_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nPublish some JSON data for device 4711:\nmosquitto_pub -h hono.eclipseprojects.io -t t/DEFAULT_TENANT/4711 -m '{\"temp\": 5}' Publish Telemetry Data (authenticated Gateway) Topic: t//${device-id} telemetry//${device-id} t/${tenant-id}/${device-id} telemetry/${tenant-id}/${device-id} Authentication: required Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This topic can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data for device 4712 via gateway gw-1:\nmosquitto_pub -h hono.eclipseprojects.io -u 'gw@DEFAULT_TENANT' -P gw-secret -t t/DEFAULT_TENANT/4712 -m '{\"temp\": 5}' Info The example above assumes that a gateway device with ID gw-1 has been registered with hashed-password credentials with auth-id gw and password gw-secret.\nPublishing Events The MQTT adapter supports the publishing of events by means of MQTT PUBLISH packets using QoS 1 only. The adapter will send an MQTT PUBACK packet to the client once the event has been accepted by the downstream messaging infrastructure.\nThis requires that\nthe events published by the client comply with the format defined by the Event API and the downstream messaging infrastructure has capacity to process events for the client’s tenant. The protocol adapter checks the configured message limit before accepting any event messages. An exceeded message limit will cause an error.\nAny kind of error when processing an incoming event message will be reported back to the client if the client has subscribed on a dedicated error topic. See Error Reporting via Error Topic for details.\nIf such an error subscription by the client exists, the error will by default be ignored after it got published on the error topic, otherwise the connection to the client will be closed. The handling of errors can further be controlled by means of an on-error property bag parameter set on the event message topic. Refer to Error Handling for details.\nAdding Meta Data Devices can add arbitrary meta data to a message by means of a property bag. The property bag is an optional collection of key/value pairs intended for the receiver of the message. The property bag is appended to the end of the topic name. It always starts with a /? character, followed by pairs of URL encoded property names and values that are separated by the \u0026 character.\nThe MQTT adapter currently supports the content-type and hono-ttl properties for publishing event messages. The former one can be used to indicate the type of data contained in the message. The latter one can be used to indicate the event’s time-to-live duration. For example, the following topic name can be used to indicate that the message contains a JSON string and should expire after 30 seconds: /topic/name/?content-type=application%2Fjson\u0026hono-ttl=30.\nPublish an Event (authenticated Device) Topic: e event Authentication: required Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttl: The message’s time-to-live in number of seconds. Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This is the preferred way for devices to publish events. It is available only if the protocol adapter has been configured to require devices to authenticate (which is the default).\nExamples\nUpload a JSON string for device 4711:\nmosquitto_pub -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t e -q 1 -m '{\"alarm\": 1}' Upload a JSON string for device 4711 with time-to-live as 10 seconds:\nmosquitto_pub -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t e/?hono-ttl=10 -q 1 -m '{\"alarm\": 1}' Publish an Event (unauthenticated Device) Topic: e/${tenant-id}/${device-id} event/${tenant-id}/${device-id} Authentication: none Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttl: The message’s time-to-live in number of seconds. Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the HONO_MQTT_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nPublish some JSON data for device 4711:\nmosquitto_pub -h hono.eclipseprojects.io -t e/DEFAULT_TENANT/4711 -q 1 -m '{\"alarm\": 1}' Publish some JSON data for device 4711 with time-to-live as 15 seconds:\nmosquitto_pub -h hono.eclipseprojects.io -t e/DEFAULT_TENANT/4711/?hono-ttl=15 -q 1 -m '{\"alarm\": 1}' Publish an Event (authenticated Gateway) Topic: e//${device-id} event//${device-id} e/${tenant-id}/${device-id} event/${tenant-id}/${device-id} Authentication: required Meta Data: (optional) content-type: The type of payload contained in the message payload. Required, if the payload is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) hono-ttl: The message’s time-to-live in number of seconds. Payload: (optional) Arbitrary payload. If the message has no payload, a non-empty content-type must be provided. This topic can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data for device 4712 via gateway gw-1:\nmosquitto_pub -h hono.eclipseprojects.io -u 'gw@DEFAULT_TENANT' -P gw-secret -t e//4712 -q 1 -m '{\"temp\": 5}' Info The example above assumes that a gateway device with ID gw-1 has been registered with hashed-password credentials with auth-id gw and password gw-secret.\nCommand \u0026 Control The MQTT adapter enables devices to receive commands that have been sent by business applications by means of sending an MQTT SUBSCRIBE packet containing a device specific topic filter as described below. Devices can subscribe with QoS 1 or QoS 0. The adapter indicates the outcome of the subscription request by sending back a corresponding SUBACK packet. The SUBACK packet will contain Success - QoS 0 (0x00) or Success - QoS 1 (0x01), indicating QoS 0 or 1, if the command topic filter is valid and the subscription was successfully registered. The SUBACK packet will contain the Failure (0x80) value in case of an invalid or unsupported filter and in case there was a (temporary) error registering the command subscription. Devices should therefore retry sending an MQTT SUBSCRIBE packet in case a SUBACK packet with the Failure value is received, provided a valid filter is used. When a device no longer wants to receive commands anymore, it can send an MQTT UNSUBSCRIBE packet to the adapter, including the same topic filter that has been used to subscribe.\nWhen a device has successfully subscribed, the adapter initiates sending an empty notification via the Command Router on behalf of the device to the downstream messaging infrastructure with the ttd header set to -1, indicating that the device will be ready to receive commands until further notice. Analogously, the adapter initiates sending an empty notification via the Command Router with the ttd header set to 0 when a device unsubscribes from commands.\nCommands can be sent following a request/response pattern or being one-way.\nFor Request/Response commands, devices send their responses to commands by means of sending an MQTT PUBLISH message to a topic that is specific to the command that has been executed. The MQTT adapter accepts responses being published using either QoS 0 or QoS 1.\nThe MQTT adapter checks the configured message limit before accepting any command requests and responses. In case of incoming command requests from business applications, if the message limit is exceeded, the Adapter rejects the message with the reason amqp:resource-limit-exceeded. And for the incoming command responses from devices, the Adapter rejects the message and closes the connection to the client.\nThe following sections define the topic filters/names to use for subscribing to and responding to commands. The following shorthand versions of topic path segments are supported:\nc instead of command q instead of req s instead of res The following variables are used:\n${command} : An arbitrary string that indicates the command to execute, e.g. setBrightness. The command is provided by the application that sends the command. ${req-id} (only for Request/Response commands) : The unique identifier of the command execution request. The identifier is passed to the device as part of the name of the topic that the command is published to. The device needs to publish its response to the command to a topic which includes this identifier, thus allowing the adapter to correlate the response with the request. ${status} : The HTTP status code indicating the outcome of executing the command. This status code is passed on to the application in the AMQP message’s status application property. Info The topic filters defined below make use of MQTT’s wild card characters in certain places of topic filters. However, the MQTT adapter does not support the general usage of wild card characters in topic filters in any other way than defined below.\nReceiving Commands (authenticated Device) An authenticated device MUST use one of the following topic filters for subscribing to commands:\nc/[${tenant-id}]/[${device-id}]/q/# command/[${tenant-id}]/[${device-id}]/req/# Both the tenant and the device ID are optional. If specified, they MUST match the authenticated device’s tenant and/or device ID. Note that the authentication identifier used in the device’s credentials is not necessarily the same as the device ID.\nThe protocol adapter will publish one-way commands for the device to the following topic names respectively:\nc/[${tenant-id}]/[${device-id}]/q//${command} command/[${tenant-id}]/[${device-id}]/req//${command} The protocol adapter will publish request-response commands for the device to the following topic names respectively:\nc/[${tenant-id}]/[${device-id}]/q/${req-id}/${command} command/[${tenant-id}]/[${device-id}]/req/${req-id}/${command} The topic name will contain\nthe tenant-id and/or device-id if the tenant and/or device ID had been included in the topic filter used for subscribing, command and req if the topic filter used for subscribing also contained the spelled-out segments. Examples\nThe following command can be used to subscribe to commands resulting in command messages being published to a topic that does not include tenant nor device ID:\nmosquitto_sub -v -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t c///q/# A request-response command with name setBrightness from an application might look like this:\nc///q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness { \"brightness\": 79 } A corresponding one-way command might look like this:\nc///q//setBrightness { \"brightness\": 79 } Note that the topic in the latter case doesn’t contain a request identifier.\nThe following command can be used to subscribe to commands resulting in command messages being published to a topic that includes the tenant ID:\nmosquitto_sub -v -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t command/DEFAULT_TENANT//req/# Note the usage of the fully spelled out names (command and req instead of c and q) and the inclusion of the tenant ID in the topic filter.\nA corresponding request-response command with name setBrightness from an application might look like this:\ncommand/DEFAULT_TENANT//req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness { \"brightness\": 79 } A corresponding one-way command might look like this:\ncommand/DEFAULT_TENANT//req//setBrightness { \"brightness\": 79 } Note that the topic also includes the tenant identifier because the topic filter used for subscribing did contain the tenant ID as well.\nReceiving Commands (unauthenticated Device) An unauthenticated device MUST use one of the following topic filters for subscribing to commands:\nc/${tenant-id}/${device-id}/q/# command/${tenant-id}/${device-id}/req/# The protocol adapter will publish one-way commands for the device to the following topic names respectively:\nc/${tenant-id}/${device-id}/q//${command} command/${tenant-id}/${device-id}/q//${command} The protocol adapter will publish request-response commands for the device to the following topic names respectively:\nc/${tenant-id}/${device-id}/q/${req-id}/${command} command/${tenant-id}/${device-id}/q/${req-id}/${command} Example\nmosquitto_sub -v -h hono.eclipseprojects.io -t c/DEFAULT_TENANT/4711/q/# A request-response command with name setBrightness from an application might look like this:\nc/DEFAULT_TENANT/4711/q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness { \"brightness\": 79 } A corresponding one-way command might look like this:\nc/DEFAULT_TENANT/4711/q//setBrightness { \"brightness\": 79 } Note that the topic in the latter case doesn’t contain a request identifier.\nReceiving Commands (authenticated Gateway) Gateway components can receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. Corresponding devices have to be configured so that they can be used with a gateway. See Connecting via a Device Gateway for details.\nAn authenticated gateway MUST use one of the following topic filters for subscribing to commands:\nTopic Filter Description c/[${tenant-id}]/+/q/#\ncommand/[${tenant-id}]/+/req/# Subscribe to commands for all devices that the gateway is authorized to act on behalf of. Also commands explicitly directed at the gateway itself will be received. c/[${tenant-id}]/${device-id}/q/#\ncommand/[${tenant-id}]/${device-id}/req/# Subscribe to commands for one specific device that the gateway is authorized to act on behalf of. The protocol adapter will publish one-way commands for devices to the following topic names respectively:\nc/[${tenant-id}]/[${device-id}]/q//${command} command/[${tenant-id}]/[${device-id}]/req//${command} The protocol adapter will publish request-response commands for devices to the following topic names respectively:\nc/[${tenant-id}]/[${device-id}]/q/${req-id}/${command} command/[${tenant-id}]/[${device-id}]/req/${req-id}/${command} The topic name will contain\nthe tenant-id segment if the tenant identifier had been included in the topic filter used for subscribing, the device-id segment in all cases except when the command was explicitly directed at the gateway itself, command and req if the topic filter used for subscribing also contained the spelled-out segments. When processing an incoming command message, the protocol adapter will give precedence to a device-specific command subscription matching the command target device, whether the subscription comes from a gateway or the device itself. If there are multiple such subscriptions from multiple gateways and/or from the device itself, the subscription initiated last will get the command messages.\nIf no device-specific command subscription exists for a command target device, but one gateway, that may act on behalf of the device, has subscribed to commands for all its devices, then the command message is sent to that gateway.\nIf multiple gateways have initiated such generic subscriptions, the protocol adapter may have to decide to which gateway a particular command message will be sent to. In case the command target device has already sent a telemetry, event or command response message via a gateway and if that gateway has created such a command subscription, that gateway will be chosen. Otherwise one gateway that may act on behalf of the command target device and that has an open subscription will be chosen randomly to receive the command message.\nIt is not possible to use both topic names command//+/req/# and command//[\u003cgateway-id\u003e]/req/# at the same time. In that case only the last such subscription would be handled from the Command Router.\nSubscribe to Commands for all Devices\nA subscription to commands for all devices that a gateway acts on behalf of looks like this:\nmosquitto_sub -v -h hono.eclipseprojects.io -u 'gw@DEFAULT_TENANT' -P gw-secret -t c/DEFAULT_TENANT/+/q/# A request/response command for device 4711 with name setBrightness from an application might then look like this:\nc/DEFAULT_TENANT/4711/q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness { \"brightness\": 79 } Note that the tenant identifier is included in the topic name that the command has been published to because it had been included in the topic filter used for subscribing to the commands.\nSubscribe to Commands for a specific Device\nA subscription to commands for a specific device can be done like this:\nmosquitto_sub -v -h hono.eclipseprojects.io -u 'gw@DEFAULT_TENANT' -P gw-secret -t c//4711/q/# A corresponding one-way command might look like this:\nc//4711/q//setBrightness { \"brightness\": 79 } Note that the topic does not include the tenant identifier because the topic filter used for subscribing did not contain the tenant ID either.\nSending a Response to a Command (authenticated Device) An authenticated device MUST send the response to a previously received command to one of the following topics:\nc///s/${req-id}/${status} command///res/${req-id}/${status} Example\nSending a response to a command using the ${req-id} from the command:\nmosquitto_pub -h hono.eclipseprojects.io -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t c///s/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{\"lumen\": 200}' Sending a Response to a Command (unauthenticated Device) An unauthenticated device MUST send the response to a previously received command to one of the following topics:\nc/${tenant-id}/${device-id}/s/${req-id}/${status} command/${tenant-id}/${device-id}/res/${req-id}/${status} Example\nSending a response to a command using the ${req-id} from the command:\nmosquitto_pub -h hono.eclipseprojects.io -t c/DEFAULT_TENANT/4711/s/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{\"lumen\": 200}' Sending a Response to a Command (authenticated Gateway) An authenticated gateway MUST send a device’s response to a command it has received on behalf of the device to one of the following topics:\nc//${device-id}/s/${req-id}/${status} command//${device-id}/res/${req-id}/${status} Example\nSending a response to a command using the ${req-id} from the command:\nmosquitto_pub -h hono.eclipseprojects.io -u 'gw@DEFAULT_TENANT' -P gw-secret -t c//4711/s/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{\"lumen\": 200}' Error Reporting via Error Topic The default behaviour when an error occurs while publishing telemetry, event or command response messages is for the MQTT adapter to close the network connection to the device, as mandated by the MQTT 3.1.1 spec.\nAn alternative way of dealing with errors involves keeping the connection intact and letting the MQTT adapter publish a corresponding error message on a specific error topic to the device. To enable that behavior, the device sends an MQTT SUBSCRIBE packet with a topic filter as described below on the same MQTT connection that is also used for publishing the telemetry, event or command response messages. Devices can subscribe with QoS 0 only. The adapter indicates the outcome of the subscription request by sending back a corresponding SUBACK packet. The SUBACK packet will contain Success - QoS 0 (0x00) for a valid error topic filter. The SUBACK packet will contain the Failure (0x80) value in case of an invalid or unsupported filter and in case a gateway is trying to subscribe on behalf of a device that doesn’t have the gateway in its list of supported via gateways. In order to again activate the default error handling behavior, the device can send an MQTT UNSUBSCRIBE packet to the adapter, including the same topic filter that has been used to subscribe.\nThe following sections define the topic filters to use for subscribing to error messages and the resulting error message topic. Instead of the error topic path segment, the shorthand version e is also supported.\nThe following variables are used:\n${endpoint-type}: The endpoint type of the device message that caused the error. Its value is either telemetry, event or the respective shorthand version. In case of a command response device message command-response or c-s is used. ${correlation-id}: The identifier that may be used to correlate the error message with the device message that caused the error. The identifier is either the value of a correlation-id property bag value contained in the device message topic, or the identifier is the packet-id of the device message if it was sent with QoS 1. Otherwise, a value of -1 is used. ${error-status}: The HTTP status code of the error that was caused by the device message. Tip Since the subscription on the error topic needs to be done on the same MQTT connection that is also used for publishing the telemetry, event or command response messages, the Mosquitto MQTT Command Line Client cannot be used. The MQTT CLI tool with its shell mode is an alternative that supports using one MQTT connection for both subscribing and publishing.\nReceiving Error Messages (authenticated Device) An authenticated device MUST use one of the following topic filters for subscribing to error messages:\ne/[${tenant-id}]/[${device-id}]/# error/[${tenant-id}]/[${device-id}]/# Both the tenant and the device ID are optional. If specified, they MUST match the authenticated device’s tenant and/or device ID. Note that the authentication identifier used in the device’s credentials is not necessarily the same as the device ID.\nThe protocol adapter will publish error messages for the device to the following topic names respectively:\ne/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status} error/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status} The topic name will contain\nthe tenant-id and/or device-id if the tenant and/or device ID had been included in the topic filter used for subscribing, error if the topic filter used for subscribing also contained the spelled-out segment. Example\nAn example using the MQTT CLI that will produce an error output if there is no downstream consumer for the device messages.\nmqtt shell con -V 3 -h hono.eclipseprojects.io -u sensor1@DEFAULT_TENANT -pw hono-secret sub -t e///# --qos 0 --outputToConsole pub -t t -m '{\"temp\": 5}' --qos 1 Using an explicit correlation id:\npub -t t/?correlation-id=123 -m '{\"temp\": 5}' --qos 1 Receiving Error Messages (unauthenticated Device) An unauthenticated device MUST use one of the following topic filters for subscribing to error messages:\nes/${tenant-id}/${device-id}/# error/${tenant-id}/${device-id}/# The protocol adapter will publish error messages for the device to the following topic names respectively:\ne/${tenant-id}/${device-id}/${endpoint-type}/${correlation-id}/${error-status} error/${tenant-id}/${device-id}/${endpoint-type}/${correlation-id}/${error-status} Receiving Error Messages (authenticated Gateway) An authenticated gateway MUST use one of the following topic filters for subscribing to error messages:\nTopic Filter Description e/[${tenant-id}]/+/#error/[${tenant-id}]/+/# Subscribe to error messages for all devices that the gateway is authorized to act on behalf of. e/[${tenant-id}]/${device-id}/#error/[${tenant-id}]/${device-id}/# Subscribe to error messages for one specific device that the gateway is authorized to act on behalf of. The protocol adapter will publish error messages for the device to the following topic names respectively:\ne/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status} error/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status} The topic name will contain\nthe tenant-id and/or device-id if the tenant and/or device ID had been included in the topic filter used for subscribing, error if the topic filter used for subscribing also contained the spelled-out segment. Error Message Payload The MQTT adapter publishes error messages with a UTF-8 encoded JSON payload containing the following fields:\nName Mandatory JSON Type Description code yes number The HTTP error status code. See the table below for possible values. message yes string The error detail message. timestamp yes string The date and time the error message was published by the MQTT adapter. The value is an ISO 8601 compliant combined date and time representation in extended format. correlation-id yes string The identifier that may be used to correlate the error message with the device message that caused the error. The identifier is either the value of a correlation-id property bag value contained in the device message topic, or the identifier is the packet-id of the device message if it was sent with QoS 1. Otherwise a value of -1 is used. The error message’s code field may contain the following HTTP status codes:\nCode Description 400 Bad Request, the request cannot be processed. A possible reason for this is an invalid PUBLISH topic. 401 Unauthorized, the device connection is not authorized (e.g. device credentials expired). 403 Forbidden, the device’s registration status cannot be asserted. 404 Not Found, the device is disabled or does not exist. 413 Request Entity Too Large, the request body exceeds the maximum supported size. 429 Too Many Requests, the tenant’s message limit for the current period is exceeded. 503 Service Unavailable, the request cannot be processed. Possible reasons for this include:There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the QoS level header is set to 1 (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. Example payload:\n{ \"code\": 400, \"message\": \"malformed topic name\", \"timestamp\": \"2020-12-24T19:00:00+0100\", \"correlation-id\": \"5\" } Error Handling When a device publishes a telemetry, event or command response message and there is an error processing the message, the handling of the error depends on whether there is a error topic subscription for the device and whether a on-error property bag parameter was set on the topic used for sending the message.\nIf no error subscription is in place and no on-error parameter was set, the default error handling behavior is to close the MQTT connection to the device. If the device has a subscription on the error topic (on the same MQTT connection the device uses for sending messages), the default behavior is to keep the MQTT connection open unless a terminal error happens. The errors that are classified as terminal are listed below.\nThe adapter is disabled for the tenant that the client belongs to. The authenticated device or gateway is disabled or not registered. The tenant is disabled or does not exist. The authenticated device is not authorized anymore (e.g. the connection expired). Info When a terminal error occurs, the connection will always be closed irrespective of any on-error parameter or error subscription.\nThe following table lists the different behaviors based on the value of the on-error property bag parameter and the existence of an error subscription:\non-error topic parameter Error subscription exists Description default or value not set no The connection to the device will get closed (like with the disconnect option). disconnect no The connection to the device will get closed. ignore no The error will be ignored and a PUBACK for the message that caused the error will get sent. skip-ack no The error will be ignored and no PUBACK for the message that caused the error will get sent. default or value not set yes After having sent an error message on the error topic, the error will be ignored and a PUBACK for the message that caused the error will get sent (like with the ignore option). disconnect yes After having sent an error message on the error topic, the connection to the device will get closed. ignore yes After having sent an error message on the error topic, the error will be ignored and a PUBACK for the message that caused the error will get sent. skip-ack yes After having sent an error message on the error topic, the error will be ignored and no PUBACK for the message that caused the error will get sent. Example\nAn authenticated device wanting to have errors always be ignored can for example publish telemetry messages on this topic:\ntelemetry/?on-error=ignore\nCustom Message Mapping This protocol adapter supports transformation of messages that have been uploaded by devices before they get forwarded to downstream consumers.\nInfo This is an experimental feature. The names of the configuration properties, potential values and the overall functionality are therefore subject to change without prior notice.\nThis feature is useful in scenarios where devices are connected to the adapter via a gateway but the gateway is not able to include the device ID in the topic that the gateway publishes data to. The gateway will use the single-segment t, e or c topics in this case. The message payload will usually contain the identifier of the device that the data originates from.\nThe same functionality can also be used to transform the payload of messages uploaded by a device. This can be used for example to transform binary encoded data into a JSON document which can be consumed more easily by downstream consumers.\nThe mechanism works as follows:\nA client uploads a message to the MQTT adapter.\nThe adapter invokes the Device Registration service’s assert Registration operation using either the authenticated device’s identifier, if the topic does not contain a device ID, or the device ID from the topic.\nIf the assertion succeeds, the adapter creates the downstream message using the original message’s payload and the asserted device ID as the origin device.\nIf the assert Registration response payload contains a value for the mapper property, the adapter tries to find a mapper endpoint configuration for the given value. If a mapper endpoint with a matching name has been configured for the adapter,\nthe adapter sends an HTTP request to the endpoint which contains the original message’s payload in the request body. If the response body is not empty, it is used as the downstream message’s payload, replacing the original payload. If the response contains a device_id header and its value is different from the original device ID, then the adapter invokes the assert Registration operation again, this time using the mapped device ID instead of the original device ID. If the assertion succeeds, the adapter uses the asserted (mapped) device ID for the downstream message. The adapter forwards the downstream message.\nPlease refer to the Device Registry Management API for how to register a mapper for a device. Please refer to the MQTT Adapter Admin Guide for how to configure custom mapper endpoints.\nDownstream Meta Data The adapter includes the following meta data in messages being sent downstream:\nName Location Type Description orig_adapter application string Contains the adapter’s type name which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The MQTT adapter’s type name is hono-mqtt. orig_address application string Contains the name of the MQTT topic that the device has originally published the data to. x-opt-retain message-annotations boolean Contains true if the device has published an event or telemetry message with its retain flag set to 1 The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:\nIf the message already contains a non-empty property of the same name, its value remains unchanged. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used. Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.\nEvent Message Time-to-live Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.\nIn most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.\nIn order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the hono-ttl property in the property-bag at the end of the event topic. Also, the default ttl and max-ttl values can be configured for a tenant/device as described in the Tenant API.\nTenant specific Configuration The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-mqtt. The following properties are (currently) supported in the Adapter object:\nName Type Default Value Description enabled boolean true If set to false the adapter will reject all data from devices belonging to the tenant. ",
    "description": "",
    "tags": null,
    "title": "MQTT Adapter",
    "uri": "/hono/docs/2.7/user-guide/mqtt-adapter/"
  },
  {
    "content": "The AMQP protocol adapter allows clients (devices or gateway components) supporting the AMQP 1.0 protocol to publish messages to Eclipse Hono™’s Telemetry, Event and Command \u0026 Control endpoints.\nDevice Authentication By default, all Hono protocol adapters require clients (devices or gateway components) to authenticate during connection establishment. This is the preferred way for devices to publish data via protocol adapters. The AMQP adapter supports both the SASL PLAIN and SASL EXTERNAL authentication mechanisms.\nThis guide provides examples for publishing telemetry and events for authenticated (using SASL PLAIN) and unauthenticated clients.\nTip The AMQP adapter can be configured to allow unauthenticated devices to connect by setting configuration variable HONO_AMQP_AUTHENTICATIONREQUIRED to false.\nSASL PLAIN Authentication The AMQP adapter supports authenticating clients using the SASL PLAIN mechanism. This means that clients need to provide a username and a password in the authcid and passwd fields of their SASL response as defined in RFC 4616, Section 2 when connecting to the AMQP adapter. The username provided in the authcid field must match the pattern auth-id@tenant, e.g. sensor1@DEFAULT_TENANT.\nThe adapter then verifies the provided username and password against the credentials that the configured Credentials service has on record for the client as described in Username/Password based Authentication. If the credentials match, the client has been authenticated successfully and the SASL handshake is completed.\nThe examples below refer to devices 4711 and gw-1 of tenant DEFAULT_TENANT using auth-ids sensor1 and gw1 and corresponding passwords. The example deployment as described in the Deployment Guide comes pre-configured with the corresponding entities in its device registry component.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nSASL EXTERNAL Authentication The AMQP adapter supports authenticating clients using the SASL EXTERNAL mechanism. This mechanism builds on top of a successful validation of an X.509 (client) certificate presented by the client during a TLS handshake as described in Client Certificate based Authentication.\nInfo The AMQP adapter needs to be configured for TLS in order to support this mechanism.\nResource Limit Checks The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.\nConnection Limits The adapter immediately closes a newly established connection with an amqp:unauthorized-access error if\nthe maximum number of connections per protocol adapter instance is reached, or if the maximum number of simultaneously connected devices for the client’s tenant is reached. Please refer to resource-limits for details.\nConnection Duration Limits The adapter immediately closes a newly established connection with an amqp:unauthorized-access error if the connection duration limit that has been configured for the client’s tenant is exceeded.\nMessage Limits The adapter\nimmediately closes a newly established connection with an amqp:unauthorized-access error and rejects any AMQP 1.0 message containing telemetry data or an event uploaded by a client a command sent by a north bound application if the message limit that has been configured for the device’s tenant is exceeded.\nConnection Events The adapter can emit Connection Events for client connections being established and/or terminated. Please refer to the common configuration options for details regarding how to enable this behavior.\nThe adapter includes the client’s AMQP container-id as the Connection Event’s remote-id.\nLink Establishment The AMQP adapter supports the Anonymous Terminus for Message Routing specification and requires clients to create a single sender link using the null target address for publishing all types of messages to the AMQP adapter.\nUsing AT MOST ONCE delivery semantics, the client will not wait for the message to be accepted and settled by the downstream consumer. However, with AT LEAST ONCE, the client sends the message and waits for the message to be delivered to and accepted by the downstream consumer. If the message cannot be delivered due to a failure, the client will be notified.\nThe client indicates its preferred message delivery mode by means of the snd-settle-mode and rcv-settle-mode fields of its attach frame during link establishment. Clients should use mixed as the snd-settle-mode and first as the rcv-settle-mode in order to be able to use the same link for sending all types of messages using different delivery semantics as described in the following sections.\nError Handling The AMQP adapter distinguishes between two types of errors when a message is published using AT LEAST ONCE delivery semantics:\nAn error caused by the client side, e.g. invalid message address, content-type, adapter disabled for tenant etc. An error caused by the server side, e.g. no downstream consumers registered, downstream connection loss etc. For a client side error, the adapter settles the message transfer with the rejected outcome and provides an error description in the corresponding disposition frame. In the case of a server-side error, the adapter settles the message with the released outcome, indicating to the client that the message itself was OK but it cannot be delivered due to a failure beyond the control of the client. In the latter case, a client may attempt to re-send the message unaltered.\nIn case of terminal errors the AMQP connection to the device is closed. The errors that are classified as terminal are listed below.\nThe adapter is disabled for the tenant that the client belongs to. The authenticated device or gateway is disabled or not registered. The tenant is disabled or does not exist. The authenticated device is not authorized anymore. Command-line Client Hono’s Command Line Client can be used to interact with the AMQP adapter. It supports sending telemetry and/or event messages as well as receiving commands and sending response messages. When invoked with the -h or --help option, the client provides an overview of the supported commands and their synopsis.\nThe following command starts the client in interactive shell mode, establishes a connection to Hono Sandbox’s AMQP adapter and prompts the user for a command to execute:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox hono-cli/amqp-device\u003e A list of available commands can be displayed using the help command, exit will close the client.\nInfo The example command above uses the default path to a Linux based system’s trusted CA certificates. The path may need to be adapted when running on a different type of operating system.\nPublishing Telemetry Data A client device indicates the delivery mode to use when uploading telemetry messages by means of the settled and rcv-settle-mode properties of the AMQP transfer frame(s) it uses for uploading a message. The AMQP adapter will accept messages using a delivery mode according to the following table:\nsettled rcv-settle-mode Delivery semantics false first The adapter will forward the message to the downstream messaging infrastructure configured for the device’s tenant.\nIn case of an AMQP 1.0 Messaging Network, the transfer will be settled with the outcome of transferring the message to the Messaging Network.\nIn case of Kafka, the transfer will be settled with outcome accepted once the message has been successfully transferred to the Kafka broker. Otherwise, the transfer will be settled with outcome released.\nThe adapter will accept any re-delivered message. Sending unsettled messages allows for clients to implement either AT LEAST ONCE or AT MOST ONCE delivery semantics, depending on whether a client actually waits for and considers the disposition frames it receives from the adapter or not. This is the recommended mode for uploading telemetry data. true first The adapter will settle the transfer of the message with the accepted outcome before forwarding it to the downstream messaging infrastructure configured for the device’s tenant. Sending pre-settled messages allows for clients to implement AT MOST ONCE delivery semantics only. This is the fastest mode of delivery but has the drawback of less reliable end-to-end flow control and potential loss of messages without notice. All other combinations are not supported by the adapter and will result in the message being ignored (pre-settled) or rejected (unsettled).\nPublish Telemetry Data (authenticated Device) Authentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: t telemetry (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. Potential reasons include that there is no active downstream consumer for messages from the device. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. When a device publishes data to the telemetry address, the AMQP adapter automatically determines the device’s identity and tenant during the authentication process.\nExamples\nStart the client in interactive mode:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox hono-cli/amqp-device\u003e Tip When interacting with Hono’s Sandbox AMQP adapter, the host, port and credentials options can be replaced by the single --sandbox option. In that case, the client will authenticate as device 4711 of the DEFAULT_TENANT.\nNow publish some JSON data for the authenticated device (4711):\n# at the hono-cli/amqp-device\u003e prompt telemetry --payload '{\"foo\": \"bar\"}' --content-type application/json Tip The message can also be sent in non-interactive mode:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox telemetry --payload '{\"foo\": \"bar\"}' --content-type application/json Note that sending the message this way will take a little longer than in interactive mode because the connection to the AMQP adapter needs to be established first. In interactive mode the connection is established during startup of the client and can then be (re-)used for sending multiple messages.\nPublish Telemetry Data (unauthenticated Device) Authentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: t/${tenant-id}/${device-id} telemetry/${tenant-id}/${device-id} (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. Potential reasons include that there is no active downstream consumer for messages from the device. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. This address format is used by devices that have not authenticated to the protocol adapter. Note that this requires the adapter’s HONO_AMQP_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExamples\nThe Hono Sandbox does not support connections from unauthenticated devices. However, if it did, the command for publishing some JSON data on behalf of device 4711 of tenant DEFAULT_TENANT would look like this:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox telemetry --tenant DEFAULT_TENANT --device 4711 --payload '{\"foo\": \"bar\"}' --content-type application/json Info The --tenant and --device options are required in this case because the command does not specify any credentials that the AMQP adapter could determine the tenant and device ID from.\nPublish Telemetry Data (authenticated Gateway) A device that publishes data on behalf of another device is called a gateway device. The message address is used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the message address is used to identify the device that the gateway publishes data for.\nAuthentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: t//${device-id} t/${tenant-id}/${device-id} telemetry//${device-id} telemetry/${tenant-id}/${device-id} (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. Potential reasons include that there is no active downstream consumer for messages from the device. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. Examples\nA gateway connecting to the adapter using gw@DEFAULT_TENANT as username and gw-secret as password and then publishing some JSON data on behalf of device 4712:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox -u gw@DEFAULT_TENANT -p gw-secret telemetry --device 4712 --payload '{\"foo\": \"bar\"}' --content-type application/json Info Note that in the command above the --sandbox option is used to indicate that the client should connect to Hono’s Sandbox AMQP adapter. The -u and -p options are then used to connect using the gateway device’s credentials instead of the default device’s.\nPublishing Events The adapter supports AT LEAST ONCE delivery of Event messages only. A client therefore MUST set the settled property to false and the rcv-settle-mode property to first in all transfer frame(s) it uses for uploading events. All other combinations are not supported by the adapter and result in the message being rejected.\nPublish an Event (authenticated Device) Authentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: e event (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. This is the preferred way for devices to publish events. It is available only if the protocol adapter has been configured to require devices to authenticate (which is the default).\nExample\nPublish a JSON string for the authenticated device (4711):\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox event --payload '{\"foo\": \"bar\"}' --content-type application/json Publish an Event (unauthenticated Device) Authentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: e/${tenant-id}/${device-id} event/${tenant-id}/${device-id} (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. This address format is used by devices that have not authenticated to the protocol adapter. Note that this requires the adapter’s HONO_AMQP_AUTHENTICATIONREQUIRED configuration property to be explicitly set to false.\nExample\nThe Hono Sandbox does not support connections from unauthenticated devices. However, if it did, the command for publishing some JSON data on behalf of device 4711 of tenant DEFAULT_TENANT would look like this:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox event --tenant DEFAULT_TENANT --device 4711 --payload '{\"foo\": \"bar\"}' --content-type application/json Info The --tenant and --device options are required in this case because the command does not specify any credentials that the AMQP adapter could determine the tenant and device ID from.\nPublish an Event (authenticated Gateway) Authentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: e//${device-id} event//${device-id} e/${tenant-id}/${device-id} event/${tenant-id}/${device-id} (optional) content-type: The type of payload contained in the message body. Required, if the message body is empty. The given content type, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. Example\nA gateway connecting to the adapter using gw@DEFAULT_TENANT as username and gw-secret as password and then publishing some JSON data on behalf of device 4712:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox -u gw@DEFAULT_TENANT -p gw-secret event --device 4712 --payload '{\"foo\": \"bar\"}' --content-type application/json Info Note that in the command above the --sandbox option is used to indicate that the client should connect to Hono’s Sandbox AMQP adapter. The -u and -p options are then used to connect using the gateway device’s credentials instead of the default device’s.\nCommand \u0026 Control The AMQP adapter enables devices to receive commands that have been sent by business applications by means of opening a receiver link using a device specific source address as described below. When a device no longer wants to receive commands anymore, it can simply close the link.\nWhen a device has successfully opened a receiver link for commands, the adapter initiates sending an empty notification via the Command Router on behalf of the device to the downstream messaging infrastructure with the ttd header set to -1, indicating that the device will be ready to receive commands until further notice. Analogously, the adapter initiates sending an empty notification via the Command Router with the ttd header set to 0 when a device closes the link or disconnects.\nDevices send their responses to commands by means of sending an AMQP message with properties specific to the command that has been executed. The AMQP adapter accepts responses being published using either at most once (QoS 0) or at least once (QoS 1) delivery semantics. The device must send the command response messages using the same (sender) link that it uses for sending telemetry data and events.\nThe AMQP adapter checks the configured message limit before accepting any command requests and responses. In case of incoming command requests from business applications or the command responses from devices, if the message limit is exceeded, the Adapter rejects the message with the reason amqp:resource-limit-exceeded.\nReceiving Commands A device MUST use the following source address in its attach frame to open a link for receiving commands:\ncommand (authenticated device) command (authenticated gateway receiving commands for all devices it acts on behalf of) command/${tenant}/${device-id} (unauthenticated device) command/${tenant}/${device-id} or command//${device-id} (authenticated gateway receiving commands for a specific device it acts on behalf of) The adapter supports AT LEAST ONCE delivery of command messages only. A client therefore MUST use unsettled for the snd-settle-mode and first for the rcv-settle-mode fields of its attach frame during link establishment. All other combinations are not supported and result in the termination of the link.\nOnce the link has been established, the adapter will send command messages having the following properties:\nName Mandatory Location Type Description subject yes properties string Contains the name of the command to be executed. reply-to no properties string Contains the address to which the command response should be sent. This property will be empty for one-way commands. correlation-id no properties string This property will be empty for one-way commands, otherwise it will contain the identifier used to correlate the response with the command request. device_id no application-properties string This property will only be set if an authenticated gateway has connected to the adapter. It will contain the id of the device (connected to the gateway) that the command is targeted at. Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See Connecting via a Device Gateway for details.\nA gateway can open a link to receive commands for all devices it acts on behalf of. An authenticated gateway can also open a receiver link for commands targeted at a specific device.\nWhen processing an incoming command message, the protocol adapter will give precedence to a device-specific command consumer matching the command target device, whether it was created by a gateway or by the device itself. If multiple such consumer links have been created, by multiple gateways and/or from the device itself, the gateway or device that last created the consumer link will get the command messages.\nIf no device-specific command consumer exists for a command target device, but one gateway, that may act on behalf of the device, has opened a generic, device-unspecific command consumer link, then the command message is sent to that gateway.\nIf multiple gateways have opened a generic command consumer link, the protocol adapter may have to decide to which gateway a particular command message will be sent to. In case the command target device has already sent a telemetry, event or command response message via a gateway and if that gateway has opened a command consumer link, that gateway will be chosen. Otherwise one gateway that may act on behalf of the command target device and that has opened a command consumer link will be chosen randomly to receive the command message.\nClients MUST settle command messages using one of the following outcomes:\naccepted: The command message has been accepted for processing. released: The command message can not be processed by the client due to a (temporary) problem at the client side. rejected: The command message can not be processed by the client because the message does not fulfill some requirements. The rejected outcome’s error field SHOULD indicate the reason why the message can not be processed. Sending a Response to a Command Devices are required to publish a response to a command that contain a reply-to address and a correlation-id. Devices may use the same anonymous sender link for this purpose that they also use for sending telemetry data and events.\nThe adapter supports AT LEAST ONCE delivery of command response messages only. A client therefore MUST set the settled property to false and the rcv-settle-mode property to first in all transfer frame(s) it uses for uploading command responses. All other combinations are not supported by the adapter and result in the message being rejected.\nAuthentication: SASL PLAIN or SASL EXTERNAL Message properties: (required) to: MUST contain the value of the reply-to property of the command request message. (required) correlation-id: MUST contain the value of the correlation-id property of the command request message. (optional) content-type: The type of payload contained in the message body. Message application-properties: (required) status: MUST contain an AMQP 1.0 int typed status code indicating the outcome of processing the command at the device (see Command \u0026 Control API for details). Message Body: (optional) Arbitrary payload contained in either a single AMQP Data or AmqpValue section. Note that the adapter only supports values of type string or array of bytes in the AmqpValue section. Values of other types will be ignored. Outcomes: accepted: The message has been successfully forwarded downstream. released: The message could not be processed by the adapter due to a (temporary) problem that has not been caused by the client. Potential reasons include that there is no active downstream consumer for messages from the device. rejected: The message could not be processed by the adapter because the client and/or the message did not fulfill some requirements. The rejected outcome’s error field will indicate the reason why the message could not be processed. Possible error conditions include: hono:bad-request: The message does not meet all formal requirements, e.g. a required property is missing. amqp:unauthorized-access: The adapter is not enabled for the tenant that the client belongs to. amqp:resource-limit-exceeded: One of the Resource Limit Checks has failed for the tenant that the client belongs to. amqp:precondition-failed: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc. Examples The AMQP adapter client can be used to simulate a device which receives commands and sends responses back to the application.\nStart the client in interactive mode:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar amqp --sandbox hono-cli/amqp-device\u003e Tip When interacting with Hono’s Sandbox AMQP adapter, the host, port and credentials options can be replaced by the single --sandbox option. In this case, the client will authenticate as device 4711 of the DEFAULT_TENANT.\nThe following command will start receiving commands for the authenticated device (4711) and automatically send a response using status code 204:\n# at the hono-cli/amqp-device\u003e prompt sub -s 204 Tip The sub command also accepts a -d option. This can be used by gateway devices to start receiving commands for one of the devices that it may act on behalf of.\nWhen a command is received, the client will print a line to the console’s standard output consisting of:\nthe type of command received (ow for a one-way and req for a request/response command) the identifier of the device that the command is targeted at (with - representing the authenticated device) the name of the command the media type describing the command’s payload the payload of the command req - setColor application/json {\"r\": 128,\"g\": 100,\"b\": 50} The following command will stop receiving commands again:\n# at the hono-cli/amqp\u003e prompt unsub With the device subscribed for commands, an application can now send commands to the device. The command line client can also be used to simulate a business application. For that purpose, open another terminal and run the following command to send a request-response command to device 4711:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar app --sandbox command req -d 4711 -n setColor --payload '{\"r\": 128,\"g\": 100,\"b\": 50}' This will result in the device’s response being printed to the console:\nres 4711 204 text/plain automatic response to [setColor] command It is also possible to send a one-way command:\n# in directory: hono/cli/target/ java -jar hono-cli-*-exec.jar app --sandbox command ow -d 4711 -n setVolume --payload '{\"level\": 50}' Downstream Meta Data The adapter includes the following meta data in messages being sent downstream:\nName Type Description orig_adapter string Contains the adapter’s type name which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The AMQP adapter’s type name is hono-amqp. orig_address string Contains the AMQP target address that the device has used to send the data. The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:\nIf the message already contains a non-empty property of the same name, its value remains unchanged. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used. Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.\nEvent Message Time-to-live Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.\nIn most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.\nIn order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the default ttl and max-ttl values configured for a tenant/device as described in the Tenant API.\nTenant specific Configuration The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-amqp. The following properties are (currently) supported:\nName Type Default Value Description enabled boolean true If set to false the adapter will reject all data from devices belonging to the tenant and respond with a amqp:unauthorized-access as the error condition value for rejecting the message. ",
    "description": "",
    "tags": null,
    "title": "AMQP Adapter",
    "uri": "/hono/docs/2.7/user-guide/amqp-adapter/"
  },
  {
    "content": "The CoAP protocol adapter exposes CoAP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nDevice Authentication The CoAP adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. The adapter (currently) supports the use of pre-shared keys (PSK) and X.509 certificates as part of a DTLS handshake for that purpose. Additional variants mentioned in Securing CoAP might be added in the future.\nPre-Shared Key The CoAP adapter supports authenticating clients using PSK based cipher suites as part of the DTLS handshake. This requires a client to provide a psk_identity in its ClientKeyExchange message as defined in RFC 4279, Section 2 during the DTLS handshake with the CoAP adapter. The adapter uses the provided information to verify the client’s identity as described in Pre-Shared Key based Authentication.\nThe examples below refer to devices 4711 and gw-1 of tenant DEFAULT_TENANT using auth-ids sensor1 and gw1 and corresponding secrets. The example deployment as described in the Deployment Guides comes pre-configured with the corresponding entities in its device registry component.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nX.509 The CoAP adapter supports authenticating clients based on TLS cipher suites using the ECDHE_ECDSA key exchange algorithm as described in RFC 4492. This requires a client to provide an X.509 client certificate containing an ECDSA-capable public key. The adapter uses the information in the client certificate to verify the device’s identity as described in Client Certificate based Authentication.\nInfo The CoAP adapter needs to be configured for DTLS in order to support this mechanism.\nMessage Limits The adapter rejects\na client’s request to upload data with status code 429 Too Many Requests and any AMQP 1.0 message containing a command sent by a north bound application if the message limit that has been configured for the device’s tenant is exceeded.\nCoAP Content Format Codes CoAP doesn’t use a textual identifier for content types. Instead, numbers are used which are maintained by the IANA. The IANA - CoAP Content Formats page lists all (currently) registered codes and the corresponding media types.\nPublish Telemetry Data (authenticated Device) URI: /t /telemetry Method: POST Type: CON: at least once delivery semantics NON: at most once delivery semantics Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c or command for one-way-commands and cr/\u003ccommand-request-id\u003e or command_response/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device. (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the message type is CON (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExamples\nThe examples provided below make use of the coap-client command line tool which is part of the libcoap project. Precompiled packages should be available for different Linux variants.\nPublish some JSON data for device 4711 using default message type CON (at least once):\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/t -t application/json -e '{\"temp\": 5}' Tip coap-client only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.\nPublish some JSON data for device 4711 using message type NON (at most once):\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret -N -m POST coaps://hono.eclipseprojects.io/t -t application/json -e '{\"temp\": 5}' Publish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/t?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info In the example above the response actually contains payload that should be used as input to a command to be executed by the device. This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could send any commands to the device.\nPublish Telemetry Data (unauthenticated Device) URI: /t/${tenantId}/${deviceId} /telemetry/${tenantId}/${deviceId} Method: PUT Type: CON: at least once delivery semantics NON: at most once delivery semantics Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c or command for one-way-commands and cr/${tenantId}/${deviceId}/\u003ccommand-request-id\u003e or command_response/${tenantId}/${deviceId}/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content). (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the message type is CON (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This resource MUST be used by devices that have not authenticated to the protocol adapter.\nInfo In order to allow devices to use this resource, the protocol adapter’s HONO_COAP_AUTHENTICATIONREQUIRED configuration property needs to be set to false explicitly.\nExamples\nPublish some JSON data for device 4711 using default message type CON (at least once):\ncoap-client -m PUT coap://hono.eclipseprojects.io/t/DEFAULT_TENANT/4711 -t application/json -e '{\"temp\": 5}' Publish some JSON data for device 4711 using message type NON (at most once):\ncoap-client -N -m PUT coap://hono.eclipseprojects.io/t/DEFAULT_TENANT/4711 -t application/json -e '{\"temp\": 5}' Publish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncoap-client -m PUT coap://hono.eclipseprojects.io/t/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info The example commands above actually do not work with the Hono Sandbox because it requires devices to always authenticate. However, these commands can be used with a custom Hono installation that allows connections from unauthenticated devices.\nPublish Telemetry Data (authenticated Gateway) URI: /t//${deviceId} /telemetry//${deviceId} /t/${tenantId}/${deviceId} /telemetry/${tenantId}/${deviceId} Method: PUT Type: CON: at least once delivery semantics NON: at most once delivery semantics Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c//${deviceId} or command//${deviceId} for one-way-commands and cr//${deviceId}/\u003ccommand-request-id\u003e or command_response//${deviceId}/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. Note that in both cases the ${deviceId} path segment indicates the device that the command is targeted at. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content). (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The tenant that the gateway belongs to is not allowed to use this protocol adapter. The device belongs to another tenant than the gateway. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). If the message type is CON (at least once semantics), the reason may be: The consumer has indicated that it didn’t process the telemetry data. The consumer failed to indicate in time whether it has processed the telemetry data. This resource can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data on behalf of device 4712 using default message type CON (at least once):\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/t//4712 -t application/json -e '{\"temp\": 5}' Publish some JSON data on behalf of device 4712 using message type NON (at most once):\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret -N -m PUT coaps://hono.eclipseprojects.io/t//4712 -t application/json -e '{\"temp\": 5}' Publish some JSON data on behalf of device 4712, indicating that the gateway will wait for 10 seconds to receive the response:\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/t//4712?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info The example above assumes that a gateway device has been registered with psk credentials with auth-id gw and secret gw-secret which is authorized to publish data on behalf of device 4712.\nPublish an Event (authenticated Device) URI: /e /event Method: POST Type:CON Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c or command for one-way-commands and cr/\u003ccommand-request-id\u003e or command_response/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content). (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This is the preferred way for devices to publish events. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExamples\nThe examples provided below make use of the coap-client command line tool which is part of the libcoap project. Precompiled packages should be available for different Linux variants.\nPublish some JSON data for device 4711 using default message type CON (at least once):\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/e -t application/json -e '{\"temp\": 5}' Tip coap-client only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.\nPublish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/e?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info In the example above the response actually contains payload that should be used as input to a command to be executed by the device. This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could send any commands to the device.\nPublish an Event (unauthenticated Device) URI: /e/${tenantId}/${deviceId} /event/${tenantId}/${deviceId} Method: PUT Type:CON Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c or command for one-way-commands and cr/${tenantId}/${deviceId}/\u003ccommand-request-id\u003e or command_response/${tenantId}/${deviceId}/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content). (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This resource MUST be used by devices that have not authenticated to the protocol adapter.\nInfo In order to allow devices to use this resource, the protocol adapter’s HONO_COAP_AUTHENTICATIONREQUIRED configuration property needs to be set to false explicitly.\nExamples\nPublish some JSON data for device 4711 using default message type CON (at least once):\ncoap-client -m PUT coap://hono.eclipseprojects.io/e/DEFAULT_TENANT/4711 -t application/json -e '{\"temp\": 5}' Publish some JSON data for device 4711, indicating that the device will wait for 10 seconds to receive the response:\ncoap-client -m PUT coap://hono.eclipseprojects.io/e/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info The example commands above actually do not work with the Hono Sandbox because it requires devices to always authenticate. However, these commands can be used with a custom Hono installation that allows connections from unauthenticated devices.\nPublish an Event (authenticated Gateway) URI: /e//${deviceId} /event//${deviceId} /e/${tenantId}/${deviceId} /event/${tenantId}/${deviceId} Method: PUT Type:CON Request Options: (optional) content-format: The type of payload contained in the request body. Required, if request body is empty but message is not an empty notification. The content type corresponding to the given content format, if not empty, will be used in the message being forwarded downstream. Otherwise, the content type of the downstream message will be set to application/octet-stream, if the payload is not empty and no default content type has been defined for the origin device or its tenant (see Downstream Meta Data). (optional) experimental option 0xfde8 (time): Request that the response include the server time. If this option is present in the request, the server will add the same option to its response where the value will indicate the server time (as milliseconds since UNIX epoch). The request option does not need to have a value, and any value will, in fact, be ignored. Query Parameters: (optional) hono-ttd: The number of seconds the device will wait for the response. (optional) hono-time: Indicates that the client wants to receive the server time as a response option. (optional) empty: Marks the request as an empty notification. Request Body: (optional) Arbitrary payload matching the given content type. Response Options: (optional) content-format: A media type describing the semantics and format of payload contained in the response body. This option will only be present if the response contains a command to be executed by the device which requires input data. Note that this option will be empty if the media type contained in the command (AMQP) message’s content-type property cannot be mapped to one of the registered CoAP content-format codes. (optional) location-query: The hono-command query parameter contains the name of the command to execute. This option will only be present if the response contains a command to be executed by the device. (optional) location-path: This option will only be present if the response contains a command to be executed by the device. The location path is c//${deviceId} or command//${deviceId} for one-way-commands and cr//${deviceId}/\u003ccommand-request-id\u003e or command_response//${deviceId}/\u003ccommand-request-id\u003e for commands expecting a response. In the latter case, the location-path option contains exactly the URI-path that the device must use when sending its response to the command. Note that in both cases the ${deviceId} path segment indicates the device that the command is targeted at. command and command_response will be used if the request also uses the fully spelled out endpoint name. (optional) experimental option 0xfde8 (time): This option will only be present if the request contained this option (with or without value) or the request contained the hono-time query parameter. The value of this option in a response will indicate the server timestamp (as milliseconds since UNIX epoch) at the time the response was sent. Response Body: (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content). (optional) Error details, if status code is \u003e= 4.00. Response Codes: 2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute. Note that if the message type is NON (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer (yet). However, if the message type is CON (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code. 4.00 (Bad Request): The request cannot be processed. Possible reasons include: The URI-query option contains the empty parameter but the request body is not empty. The request body is empty but the request has no content-format set nor does its URI-query option contain the empty parameter. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The tenant that the gateway belongs to is not allowed to use this protocol adapter. The device belongs to another tenant than the gateway. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event. This resource can be used by gateway components to publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nPublish some JSON data on behalf of device 4712 using default message type CON (at least once):\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/e//4712 -t application/json -e '{\"temp\": 5}' Publish some JSON data on behalf of device 4712, indicating that the gateway will wait for 10 seconds to receive the response:\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/e//4712?hono-ttd=10 -t application/json -e '{\"temp\": 5}' { \"brightness\": 87 } Info The example above assumes that a gateway device has been registered with psk credentials with auth-id gw and secret gw-secret which is authorized to publish data on behalf of device 4712.\nCommand \u0026 Control The CoAP adapter enables devices to receive commands that have been sent by business applications. Commands are delivered to the device by means of a response message. That means a device first has to send a request, indicating how long it will wait for the response. That request can either be a telemetry or event message, with a hono-ttd query parameter (time till disconnect) specifying the number of seconds that the device will wait for the response. The business application can react on that message by sending a command message, targeted at the device. The CoAP adapter will then send the command message as part of the response message to the device.\nCommands handled by gateways Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See Connecting via a Device Gateway for details.\nA gateway can send a request with the hono-ttd query parameter on the /e or /t URIs, indicating its readiness to receive a command for any of the devices that it acts on behalf of. Note that in this case, the business application will be notified with the gateway’s identifier in the device_id property of the downstream message.\nAn authenticated gateway can also indicate its readiness to receive a command targeted at a specific device. For that, the /e//${deviceId} or /t//${deviceId} URIs are to be used, containing the identifier of the device to receive a command for. The business application will receive a notification with that device identifier.\nIf there are multiple concurrent requests with a hono-ttd query parameter, sent by the command target device and/or one or more of its potential gateways, the CoAP adapter will choose the device or gateway to send the command to as follows:\nA request done by the command target device or by a gateway specifically done for that device, has precedence. If there are multiple concurrent such requests, the last one will get the command message (if received) in its response. Note that the other requests won’t be answered with a command message in their response event if the business application sent multiple command messages. This means that commands for a single device can only be requested sequentially, but not in parallel. If the above doesn’t apply, a single hono-ttd request on the /e or /t URIs, sent by a gateway that the command target device is configured for, will get the command message in its response. If there are multiple concurrent such requests by different gateways, all configured for the command target device, the request by the gateway will be chosen, through which the target device has last sent a telemetry or event message. If the target device hasn’t sent a message yet and it is thereby unknown via which gateway the device communicates, then one of the requests will be chosen randomly to include the command in its response. Sending a Response to a Command (authenticated Device) URI: /cr/${commandRequestId} /command_response/${commandRequestId} Method: POST Type: CON Request Options: (optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This option must be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body. Query Parameters: (required) hono-cmd-status: An HTTP status code indicating the outcome of processing the command. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Codes: 2.04 (Changed): The response has been successfully delivered to the application that has sent the command. 4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This is the preferred way for devices to respond to commands. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).\nExample\nSend a response to a previously received command with the command-request-id req-id-uuid for device 4711:\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/cr/req-id-uuid?hono-cmd-status=200 Sending a Response to a Command (unauthenticated Device) URI: /cr/${tenantId}/${deviceId}/${commandRequestId} /command_response/${tenantId}/${deviceId}/${commandRequestId} Method: PUT Type: CON Request Options: (optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This option must be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body. Query Parameters: (required) hono-cmd-status: An HTTP status code indicating the outcome of processing the command. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Codes: 2.04 (Changed): The response has been successfully delivered to the application that has sent the command. 4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This resource MUST be used by devices that have not authenticated to the protocol adapter.\nInfo In order to allow devices to use this resource, the protocol adapter’s HONO_COAP_AUTHENTICATIONREQUIRED configuration property needs to be set to false explicitly.\nExamples\nSend a response to a previously received command with the command-request-id req-id-uuid for the unauthenticated device 4711:\ncoap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/cr/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status=200 -e '{\"brightness-changed\": true}' Info The example command above actually does not work with the Hono Sandbox because it requires devices to always authenticate. However, this command can be used with a custom Hono installation that allows connections from unauthenticated devices.\nSending a Response to a Command (authenticated Gateway) URI: /cr//${deviceId}/${commandRequestId} /command_response//${deviceId}/${commandRequestId} /cr/${tenantId}/${deviceId}/${commandRequestId} /command_response/${tenantId}/${deviceId}/${commandRequestId} Method: PUT Type: CON Request Options: (optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This option must be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body. Query Parameters: (required) hono-cmd-status: An HTTP status code indicating the outcome of processing the command. Request Body: (optional) Arbitrary data representing the result of processing the command on the device. Response Codes: 2.04 (Changed): The response has been successfully delivered to the application that has sent the command. 4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed. 4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include: The given tenant is not allowed to use this protocol adapter. The given device does not belong to the given tenant. The gateway is not authorized to act on behalf of the device. The gateway associated with the device is not registered or disabled. 4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist. 4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size. 4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded. 5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: There is no application listening for a reply to the given commandRequestId. The application has already given up on waiting for a response. This resource can be used by gateway components to send the response to a command on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like SigFox or LoRa. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.\nThe protocol adapter checks the gateway’s authority to send responses to a command on behalf of the device implicitly by means of retrieving a registration assertion for the device from the configured Device Registration service.\nExamples\nSend a response to a previously received command with the command-request-id req-id-uuid on behalf of device 4712:\ncoap-client -u gw@DEFAULT_TENANT -k gw-secret coaps://hono.eclipseprojects.io/cr//4712/req-id-uuid?hono-cmd-status=200 -e '{\"brightness-changed\": true}' Info The example above assumes that a gateway device has been registered with psk credentials with auth-id gw and secret gw-secret which is authorized to publish data on behalf of device 4712.\nDownstream Meta Data The adapter includes the following meta data in messages being sent downstream:\nName Type Description device_id string The identifier of the device that the message originates from. orig_adapter string Contains the adapter’s type name which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The CoAP adapter’s type name is hono-coap. orig_address string Contains the (relative) URI that the device has originally posted the data to. ttd integer Contains the effective number of seconds that the device will wait for a response. This property is only set if the request contains the hono-ttd URI-query option. The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:\nIf the message already contains a non-empty property of the same name, its value remains unchanged. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used. Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.\nEvent Message Time-to-live Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.\nIn most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.\nIn order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the default ttl and max-ttl values configured for a tenant/device as described in the Tenant API.\nTenant specific Configuration The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-coap. The following properties are (currently) supported:\nName Type Default Value Description enabled boolean true If set to false the adapter will reject all data from devices belonging to the tenant. max-ttd integer 60 Defines a tenant specific upper limit for the time until disconnect property that devices may include in requests for uploading telemetry data or events. Please refer to the Command \u0026 Control concept page for a discussion of this parameter’s purpose and usage.\nThis property can be set for the hono-coap adapter type as an extension property in the adapter section of the tenant configuration.\nIf it is not set, then the default value of 60 seconds is used. timeoutToAck integer - This property has the same semantics as the corresponding property at the adapter level. However, any (non-null) value configured for a tenant takes precedence over the adapter level value for all devices of the particular tenant. ",
    "description": "",
    "tags": null,
    "title": "CoAP Adapter",
    "uri": "/hono/docs/2.7/user-guide/coap-adapter/"
  },
  {
    "content": "The Sigfox protocol adapter exposes an HTTP endpoint for connecting up with the Sigfox backend for publishing telemetry, events and use command \u0026 control.\nInfo This protocol adapter is not considered production ready. Its APIs might still be subject to change without warning.\nPre-requisites This Sigfox adapter only connects to the Sigfox backend system (backend.sigfox.com). It does not allow direct access to Sigfox devices.\nSo you need to set up your Sigfox devices on backend.sigfox.com and then configure the callbacks connect to your installation of Hono.\nDevices and credentials In a nutshell, the Sigfox adapter requires a single device identity, acting as a gateway device. This identity will be used to connect to Hono. All devices registered with Sigfox (the actual Sigfox devices), will be registered in Hono to allow this first identity as their gateway device.\nSetup example The following sub-sections walk you through an example setup.\nRegistering devices This example assumes that the Sigfox protocol adapter is available as https://iot-sigfox-adapter.my.hono.\nCreate a new gateway device with the following registration:\n{ \"device-id\": \"sigfox-backend\" } Create new credentials for the gateway device. For example, using a username of sigfox and a password of test12:\n{ \"auth-id\": \"sigfox\", \"device-id\": \"sigfox-backend\", \"enabled\": true, \"secrets\": [ { \"pwd-plain\": \"test12\" } ], \"type\": \"hashed-password\" } Create a new device, referencing the previous gateway device. The device id must be your Sigfox device ID (e.g. 1AB2C3):\n{ \"device-id\": \"1AB2C3\", \"via\": \"sigfox-backend\" } Setting up callbacks Log in to the Sigfox backend at https://backend.sigfox.com and then open up the view Device Type -\u003e Callbacks.\nCreate a new “Custom” callback, with the following settings (replacing \u003cTENANT\u003e with the name of the tenant):\nType: DATA – UPLINK Channel: URL Url pattern: https://iot-sigfox-adapter.my.hono/data/telemetry/\u003cTENANT\u003e?device={device}\u0026data={data} Use HTTP Method: GET Headers Authorization – Basic … (see note below) Send SNI: ☑ (Enabled) Tip At the moment you need to manually put in the Authorization header, you cannot put the credentials into the URL, as there is a bug in the Sigfox backend, which cannot be fixed by Hono. The backend does not properly escape the @ character, and thus sends foo%40tenant instead of foo@tenant to the Hono protocol adapter.\nAs a workaround, you can explicitly set the Authorization header to a value of Basic \u003cbase64 encoded credentials\u003e. You can encode the credentials using:\necho -n \"sigfox@tenant:password\" | base64 To get the full value, including the Basic you may use:\necho \"Basic $(echo -n \"sigfox@tenant:password\" | base64)\" Enabling command \u0026 control It is possible to enable command \u0026 control as well. For this you need to:\nSwitch the Type of the DATA callback from UPLINK to BIDIR Add the ack query parameter to the Url pattern, e.g. https://iot-sigfox-adapter.my.hono/data/telemetry/\u003cTENANT\u003e?device={device}\u0026data={data}\u0026ack={ack} Tip Sigfox allows only a very specific payload in command messages. You must send exactly 8 bytes of data. It only supports one way commands.\nEvents You can send events by using the path /data/event on the URL.\nConsuming data Use the standard way of consuming Hono messages.\nKnown bugs and limitations Only the simple URL and only data (no service or device events are currently supported. ",
    "description": "",
    "tags": null,
    "title": "Sigfox Adapter",
    "uri": "/hono/docs/2.7/user-guide/sigfox-adapter/"
  },
  {
    "content": "Admin Guide Learn how to operate Eclipse Hono™ and look up the configuration options of its components.\n",
    "description": "",
    "tags": null,
    "title": "Admin Guide",
    "uri": "/hono/docs/2.7/admin-guide/"
  },
  {
    "content": "Many Hono components support a common set of configuration options. This section describes those options.\nEach component which supports the following options explicitly states so. If it doesn’t, then these options are not supported by this component.\nJava 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.\nEnvironment Variable Mandatory Default Description JDK_JAVA_OPTIONS no - Any options that should be passed to the Java VM on the command line, e.g. -Xmx128m 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:\nOS Environment Variable\nJava System Property Mandatory Default Description QUARKUS_VERTX_MAX_EVENT_LOOP_EXECUTE_TIME\nquarkus.vertx.max-event-loop-execute-time no PT2S The maximum duration that a task on the event loop may run without being considered to block the event loop. The value needs to be a string that represents an ISO-8601 Duration. QUARKUS_VERTX_PREFER_NATIVE_TRANSPORT\nquarkus.vertx.prefer-native-transport no true Enables/disables epoll() support on Linux/MacOS. See the notes below for an explanation of the benefits of enabling epoll. It is generally safe to set this property to true because Netty will disable native transport if the platform doesn’t support it. 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.\nThe Netty framework supports using epoll() on Linux/MacOS x86_64 based systems.\nHono’s components support native transport out of the box.\nProtocol Adapter Options Messaging Configuration Protocol adapters use a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to\nforward telemetry data and events received from devices so that they can be received by downstream consumers, receive command \u0026 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 more than one kind of messaging is configured, the decision which one to use is done according to the Tenant Configuration.\nCommand 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.\nFor notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.\nAMQP 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.\nKafka based Messaging Configuration The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.\nThe 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.\nOS Environment Variable Prefix\nJava System Property Prefix Description HONO_KAFKA_COMMAND_CONSUMERCONFIG_\nhono.kafka.command.consumerConfig. Configures the Kafka consumer that receives command messages. HONO_KAFKA_COMMANDINTERNAL_ADMINCLIENTCONFIG_\nhono.kafka.commandInternal.adminClientConfig. Configures the Kafka admin client that creates Hono internal topics. HONO_KAFKA_COMMANDRESPONSE_PRODUCERCONFIG_\nhono.kafka.commandResponse.producerConfig. Configures the Kafka producer that publishes command response messages. HONO_KAFKA_EVENT_PRODUCERCONFIG_\nhono.kafka.event.producerConfig. Configures the Kafka producer that publishes event messages. HONO_KAFKA_NOTIFICATION_CONSUMERCONFIG_\nhono.kafka.notification.consumerConfig. Configures the Kafka consumer that receives notification messages about changes to tenant/device/credentials data. HONO_KAFKA_TELEMETRY_PRODUCERCONFIG_\nhono.kafka.telemetry.producerConfig. Configures the Kafka producer that publishes telemetry messages. Google Pub/Sub Connection Configuration The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.\nTenant Service Connection Configuration Protocol adapters require a connection to an implementation of Hono’s Tenant API in order to retrieve information for a tenant.\nThe 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.\nThe 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.\nDevice 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.\nThe connection to the Device Registration Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_REGISTRATION.\nThe 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.\nNote 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.\nCredentials 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.\nThe connection to the Credentials Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_CREDENTIALS.\nThe 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.\nNote 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.\nCommand 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 \u0026 control messages to the protocol adapters that the target devices are connected to.\nThe connection to the Command Router service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_COMMANDROUTER.\nResponses from the Command Router service are never cached, so the properties for configuring the cache are ignored.\nResource 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.\nThe following table provides an overview of the configuration variables and corresponding system properties for configuring the checker.\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_RESOURCELIMITS_PROMETHEUSBASED_HOST\nhono.resourceLimits.prometheusBased.host no localhost The host name or IP address of the Prometheus server to retrieve the metrics data from. This property needs to be set in order to enable the Prometheus based checks. HONO_RESOURCELIMITS_PROMETHEUSBASED_PORT\nhono.resourceLimits.prometheusBased.port no 9090 The port of the Prometheus server to retrieve metrics data from. HONO_RESOURCELIMITS_PROMETHEUSBASED_CACHEMINSIZE\nhono.resourceLimits.prometheusBased.cacheMinSize no 20 The minimum size of the cache to store the metrics data retrieved from the Prometheus server. The cache is used for storing the current amount of data exchanged with devices of tenants. HONO_RESOURCELIMITS_PROMETHEUSBASED_CACHEMAXSIZE\nhono.resourceLimits.prometheusBased.cacheMaxSize no 1000 The maximum size of the cache to store the metrics data retrieved from the Prometheus server. HONO_RESOURCELIMITS_PROMETHEUSBASED_CACHETIMEOUT\nhono.resourceLimits.prometheusBased.cacheTimeout no 60 The number of seconds after which the cached metrics data should be considered invalid. HONO_RESOURCELIMITS_PROMETHEUSBASED_CACHEREFRESHDIVISOR\nhono.resourceLimits.prometheusBased.cacheRefreshDivisor no 2 The divisor used to calculate the refresh time duration after which cached metrics data refreshing in the background is allowed. The duration is calculated as the cache timeout duration divided by this value. HONO_RESOURCELIMITS_PROMETHEUSBASED_CONNECTTIMEOUT\nhono.resourceLimits.prometheusBased.connectTimeout no 1000 The maximum number of milliseconds that the adapter waits for a TCP connection to a Prometheus server to be established. HONO_RESOURCELIMITS_PROMETHEUSBASED_QUERYTIMEOUT\nhono.resourceLimits.prometheusBased.queryTimeout no 500 The number of milliseconds after which a request to a Prometheus server is closed. Setting zero or a negative value disables the timeout. 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.\nHONO_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.\nThe producer being used by the adapter can be configured as follows:\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_CONNECTIONEVENTS_PRODUCER\nhono.connectionEvents.producer no logging The type of connection event producer to use for reporting the establishment/termination of device connections. Supported values are\nnone - No information is reported at all.\nlogging - All information is reported at INFO level via the logging framework.\nevents - All information is being sent downstream as Connection Events. HONO_CONNECTIONEVENTS_LOGLEVEL\nhono.connectionEvents.logLevel no info The level to log connection information at. Supported values are debug and info. The events based connection event producer sets the TTL of event messages that it emits to the max TTL configured at the tenant level.\n",
    "description": "",
    "tags": null,
    "title": "Common Configuration",
    "uri": "/hono/docs/2.7/admin-guide/common-config/"
  },
  {
    "content": "The Auth Server component exposes a service endpoint implementing Eclipse Hono™’s Authentication API. Other services use this component for authenticating clients and retrieving a JSON Web Token (JWT) asserting the client’s identity and corresponding authorities.\nThis component serves as a default implementation of the Authentication API only. On startup, it reads in all identities and their authorities from a JSON file from the file system. All data is then kept in memory and there are no remote service APIs for managing the identities and their authorities.\nThe Auth Server 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.\nInfo The Auth Server had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the Auth Server component:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. HONO_AUTH_AMQP_BINDADDRESS\nhono.auth.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_AUTH_AMQP_CERTPATH\nhono.auth.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_AUTH_AMQP_KEYPATH.\nAlternatively, the HONO_AUTH_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_AUTH_AMQP_INSECUREPORT\nhono.auth.amqp.insecurePort no - The insecure port the server should listen on.\nSee Port Configuration below for details. HONO_AUTH_AMQP_INSECUREPORTBINDADDRESS\nhono.auth.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_AUTH_AMQP_INSECUREPORTENABLED\nhono.auth.amqp.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_AUTH_AMQP_INSECUREPORT or the default AMQP port number (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_AUTH_AMQP_KEYPATH\nhono.auth.amqp.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the server should use for authenticating to clients. Note that the private key is not protected by a password. You should therefore make sure that the key file can only be read by the user that the server process is running under. This option must be used in conjunction with HONO_AUTH_CERTPATH.\nAlternatively, the HONO_AUTH_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_AUTH_AMQP_KEYSTOREPASSWORD\nhono.auth.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_AUTH_AMQP_KEYSTOREPATH\nhono.auth.amqp.keyStorePath no - 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_AUTH_AMQP_KEYPATH and HONO_AUTH_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_AUTH_AMQP_NATIVETLSREQUIRED\nhono.auth.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_AUTH_AMQP_PORT\nhono.auth.amqp.port no 5671 The secure port that the server should listen on.\nSee Port Configuration below for details. HONO_AUTH_AMQP_SECUREPROTOCOLS\nhono.auth.amqp.secureProtocols no TLSv1.2 A (comma separated) list of secure protocols that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_AUTH_AMQP_SUPPORTEDCIPHERSUITES\nhono.auth.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_AUTH_AMQP_TRUSTSTOREPASSWORD\nhono.auth.amqp.trustStorePassword no - The password required to read the contents of the trust store. HONO_AUTH_AMQP_TRUSTSTOREPATH\nhono.auth.amqp.trustStorePath no - The absolute path to the Java key store containing the CA certificates the service uses for authenticating clients. The key store format can be either JKS, PKCS12 or PEM indicated by a .jks, .p12 or .pem file suffix respectively. HONO_AUTH_SVC_PERMISSIONSPATH\nhono.auth.svc.permissionsPath yes - The path to the JSON file defining the identities and corresponding authorities on Hono’s endpoint resources. For backwards compatibility with previous releases, the path may contain a file:// prefix. HONO_AUTH_SVC_SUPPORTEDSASLMECHANISMS\nhono.auth.svc.supportedSaslMechanisms no EXTERNAL, PLAIN A (comma separated) list of the supported SASL mechanisms to be advertised to clients. This option may be set to specify only one of EXTERNAL or PLAIN, or to use a different order. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Monitoring Options YAML File based Configuration The configuration properties can also be set by means of a YAML file as described in the Quarkus documentation.\nPort Configuration The Auth Server can be configured to listen for connections on\na 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.\nSecure Port Only The server needs to be configured with a private key, a certificate holding the public key and a trust store in order to open a TLS secured port.\nThere are two alternative ways for setting the private key and certificate:\nSetting the HONO_AUTH_AMQP_KEYSTORE_PATH and the HONO_AUTH_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_AUTH_AMQP_KEYPATH and HONO_AUTH_AMQPCERTPATH variables in order to load the key and certificate from two separate PEM files in PKCS8 format. In order to set the trust store, the HONO_AUTH_AMQP_TRUSTSTOREPATH variable needs to be set to a key store containing the trusted root CA certificates. The HONO_AUTH_AMQP_TRUSTSTOREPASSWORD variable needs to be set if the key store requires a pass phrase for reading its contents.\nWhen 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_AUTH_AMQP_PORT variable.\nThe HONO_AUTH_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 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).\nInsecure 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\nexplicitly setting HONO_AUTH_AMQP_INSECUREPORT to a valid port number, or by implicitly configuring the default AMQP port (5672) by simply setting HONO_AUTH_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if HONO_AUTH_AMQP_INSECUREPORT is set to the default secure AMQP port (5671).\nThe HONO_AUTH_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_AUTH_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The Auth Server will then use arbitrary (unused) port numbers determined by the operating system during startup.\nSigning Key Configuration The Auth server needs to be configured with key material that can be used to digitally sign the tokens that it creates.\nThe following table provides an overview of the configuration variables and corresponding system properties for configuring the Auth server’s signing process:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_SVC_SIGNING_AUDIENCE\nhono.auth.svc.signing.audience no - The value to put into a created token’s aud claim. HONO_AUTH_SVC_SIGNING_ISSUER\nhono.auth.svc.signing.issuer yes https://hono.eclipse.org/auth-server The value to put into a created token’s iss claim. HONO_AUTH_SVC_SIGNING_KEYPATH\nhono.auth.svc.signing.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the server should use for signing tokens asserting an authenticated client’s identity and authorities. When using this variable, other services that need to validate the tokens issued by this service need to be configured with the corresponding certificate/public key. Alternatively, a symmetric key can be used for signing (and validating) by setting the HONO_AUTH_SVC_SIGNING_SHAREDSECRET variable. If none of these variables is set, the server falls back to the key indicated by the HONO_AUTH_AMQP_KEYPATH variable. If that variable is also not set, startup of the server fails. HONO_AUTH_SVC_SIGNING_SHAREDSECRET\nhono.auth.svc.signing.sharedSecret no - A string to derive a symmetric key from that is used for signing tokens asserting an authenticated client’s identity and authorities. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the signing key using this variable, other services that need to validate the tokens issued by this service need to be configured with the same key. Alternatively, an asymmetric key pair can be used for signing (and validating) by setting the HONO_AUTH_SVC_SIGNING_KEYPATH variable. If none of these variables is set, startup of the server fails. HONO_AUTH_SVC_SIGNING_TOKENEXPIRATION\nhono.auth.svc.signing.tokenExpiration no 600 The number of seconds after which the tokens created by this service for asserting an authenticated client’s identity should be considered invalid. Other Hono components will close AMQP connections with clients after this period in order to force the client to authenticate again and create a new token. In closed environments it should be save to set this value to a much higher value, e.g. several hours. JSON Web Key Set Resource Configuration The Auth server hosts an HTTP resource under URI /validating-keys that other components can use to retrieve a JSON Web Key set that contains the keys to use for validating the signature of tokens created by the Auth server.\nThe resource is served by the same HTTP server that is also used for hosting the health check resources described in the Monitoring \u0026 Tracing Admin Guide.\nMetrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\n",
    "description": "",
    "tags": null,
    "title": "Auth Server Configuration",
    "uri": "/hono/docs/2.7/admin-guide/auth-server-config/"
  },
  {
    "content": "The MongoDB based Device Registry component provides an implementation of Eclipse Hono™’s Device Registration, Credentials and Tenant APIs. Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it. In addition to the above, this Device Registry also provides an implementation of Device Registry Management APIs for managing tenants, registration information and credentials of devices.\nThe registry is implemented as a Quarkus application, using a MongoDB database as the persistence store. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.\nThe registry is compatible and known to work with the following MongoDB versions:\nMongoDB 6.0 MongoDB 7.0 Info Support for Mongo DB 5.0 has been removed from Hono after it had reached its end of life in Oct 2024.\nWarning According to the Mongo DB Software Lifecycle Schedule support for Mongo DB 6.0 has ended Jul 2025. Consequently, support for Mongo 6.0 in Hono has been deprecated and will be removed in a future version altogether. Users are encouraged to migrate to Mongo DB 7.0. Note that Hono currently does not support Mongo DB 8.0 because of the specific driver version being required by the vertx-mongo-client library.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the MongoDB based Device Registry.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_CREDENTIALS_SVC_CACHEMAXAGE\nhono.credentials.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_CREDENTIALS_SVC_COLLECTIONNAME\nhono.credentials.svc.collectionName no credentials The name of the MongoDB collection where the server stores credentials of devices. HONO_CREDENTIALS_SVC_ENCRYPTIONKEYFILE\nhono.credentials.svc.encryptionKeyFile no - The path to the YAML file that encryption keys should be read from. HONO_CREDENTIALS_SVC_HASHALGORITHMSWHITELIST\nhono.credentials.svc.hashAlgorithmsWhitelist no empty An array of supported hashing algorithms to be used with the hashed-password type of credentials. When not set, all values will be accepted. HONO_CREDENTIALS_SVC_MAXBCRYPTCOSTFACTOR\nhono.credentials.svc.maxBcryptCostFactor no 10 The maximum cost factor that is supported in password hashes using the BCrypt hash function. This limit is enforced by the device registry when adding or updating corresponding credentials. Increasing this number allows for potentially more secure password hashes to be used. However, the time required to compute the hash increases exponentially with the cost factor. HONO_MONGODB_CONNECTIONSTRING\nhono.mongodb.connectionString no - The connection string used by the Device Registry application to connect to the MongoDB database. If this property is set, it overrides the other MongoDB connection settings.\nSee Connection String URI Format for more information. HONO_MONGODB_CONNECTIONTIMEOUTINMS\nhono.mongodb.connectionTimeoutInMs no 10000 The time in milliseconds to attempt a connection before timing out. HONO_MONGODB_DBNAME\nhono.mongodb.dbName no - The name of the MongoDB database that should be used by the Device Registry application. HONO_MONGODB_HOST\nhono.mongodb.host no localhost The host name or IP address of the MongoDB instance. HONO_MONGODB_PORT\nhono.mongodb.port no 27017 The port that the MongoDB instance is listening on. HONO_MONGODB_PASSWORD\nhono.mongodb.password no - The password to use for authenticating to the MongoDB instance. HONO_MONGODB_SERVERSELECTIONTIMEOUTINMS\nhono.mongodb.serverSelectionTimeoutInMs no 1000 The time in milliseconds that the mongo driver will wait to select a server for an operation before raising an error. HONO_MONGODB_USERNAME\nhono.mongodb.username no - The user name to use for authenticating to the MongoDB instance. HONO_REGISTRY_AMQP_BINDADDRESS\nhono.registry.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_CERTPATH\nhono.registry.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_REGISTRY_AMQP_KEYPATH.\nAlternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_INSECUREPORT\nhono.registry.amqp.insecurePort no - The insecure port the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS\nhono.registry.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTENABLED\nhono.registry.amqp.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_AMQP_INSECUREPORT or the default AMQP port number (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_KEYPATH\nhono.registry.amqp.keyPath no - 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_REGISTRY_AMQP_CERTPATH. Alternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_KEYSTOREPASSWORD\nhono.registry.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_AMQP_KEYSTOREPATH\nhono.registry.amqp.keyStorePath no - 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_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_AMQP_NATIVETLSREQUIRED\nhono.registry.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_REGISTRY_AMQP_PORT\nhono.registry.amqp.port no 5671 The secure port that the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_RECEIVERLINKCREDIT\nhono.registry.amqp.receiverLinkCredit no 100 The number of credits to (initially) flow to a client connecting to one of the registry’s endpoints. HONO_REGISTRY_AMQP_SECUREPROTOCOLS\nhono.registry.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_AMQP_SUPPORTEDCIPHERSUITES\nhono.registry.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_HTTP_AUTH_COLLECTIONNAME\nhono.registry.http.auth.collectionName no user The name of the Mongo collection that contains the user accounts that are authorized to access the HTTP endpoint. Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTH_HASHALGORITHM\nhono.registry.http.auth.hashAlgorithm no PBKDF2 DEPRECATED The name of the property that contains the algorithm to be used for creating the password hash. Valid values are PBKDF2 and SHA512. Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTH_PASSWORDFIELD\nhono.registry.http.auth.passwordField no password The name of the property that contains an account’s password. Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTH_SALTFIELD\nhono.registry.http.auth.saltField no salt DEPRECATED The name of the property that contains a password hash’s salt (if the HONO_REGISTRY_HTTP_AUTH_SALTSTYLE has value COLUMN). Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTH_SALTSTYLE\nhono.registry.http.auth.saltStyle no COLUMN DEPRECATED The strategy to use for storing password salt values. Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTH_USERNAMEFIELD\nhono.registry.http.auth.usernameField no username The name of the property that contains an account’s user name. Please refer to the vert.x documentation for details. HONO_REGISTRY_HTTP_AUTHENTICATIONREQUIRED\nhono.registry.http.authenticationRequired no true If set to true the HTTP endpoint of the Device Registry requires clients to authenticate when connecting to the Device Registry. The MongoDB based Device Registry currently supports basic authentication with user credentials being read from a Mongo collection defined by HONO_REGISTRY_HTTP_AUTH_COLLECTIONNAME. For more information on how to manage users please refer to Mongo Auth Provider. HONO_REGISTRY_HTTP_BINDADDRESS\nhono.registry.http.bindAddress no 127.0.0.1 The IP address of the network interface that the secure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_CERTPATH\nhono.registry.http.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_REGISTRY_HTTP_KEYPATH.\nAlternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_DEVICEIDPATTERN\nhono.registry.http.deviceIdPattern no ^[a-zA-Z0-9-_\\.:]+$ The regular expression to use to validate device ID. Please refer to the java pattern documentation. HONO_REGISTRY_HTTP_IDLETIMEOUT\nhono.registry.http.idleTimeout no 60 The idle timeout in seconds. A connection will timeout and be closed if no data is received or sent within the idle timeout period. A zero value means no timeout is used. HONO_REGISTRY_HTTP_INSECUREPORT\nhono.registry.http.insecurePort no - The insecure port the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTBINDADDRESS\nhono.registry.http.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTENABLED\nhono.registry.http.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_HTTP_INSECUREPORT or the default HTTP port number (8080) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_KEYPATH\nhono.registry.http.keyPath no - 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_REGISTRY_HTTP_CERTPATH. Alternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_KEYSTOREPASSWORD\nhono.registry.http.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_HTTP_KEYSTOREPATH\nhono.registry.http.keyStorePath no - 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_REGISTRY_HTTP_KEYPATH and HONO_REGISTRY_HTTP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_HTTP_MAXPAYLOADSIZE\nhono.registry.http.maxPayloadSize no 16000 The maximum size of an HTTP request body in bytes that is accepted by the registry. HONO_REGISTRY_HTTP_PORT\nhono.registry.http.port no 8443 The secure port that the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_SECUREPROTOCOLS\nhono.registry.http.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_HTTP_SUPPORTEDCIPHERSUITES\nhono.registry.http.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_HTTP_TENANTIDPATTERN\nhono.registry.http.tenantIdPattern no ^[a-zA-Z0-9-_\\.]+$ The regular expression to use to validate tenant ID. Please refer to the java pattern documentation. HONO_REGISTRY_SVC_CACHEMAXAGE\nhono.registry.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_REGISTRY_SVC_COLLECTIONNAME\nhono.registry.svc.collectionName no devices The name of the MongoDB collection where the server stores registered device information. HONO_REGISTRY_SVC_MAXDEVICESPERTENANT\nhono.registry.svc.maxDevicesPerTenant no -1 The number of devices that can be registered for each tenant. It is an error to set this property to a value \u003c -1. The value -1 indicates that no limit is set. HONO_REGISTRY_SVC_USERNAMEPATTERN\nhono.registry.svc.usernamePattern no ^[a-zA-Z0-9-_=\\\\.]+$ The regular expression to use for validating authentication identifiers (user names) of hashed-password credentials. HONO_TENANT_SVC_CACHEMAXAGE\nhono.tenant.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_TENANT_SVC_COLLECTIONNAME\nhono.tenant.svc.collectionName no tenants The name of the MongoDB collection where the server stores tenants information. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Monitoring Options Port Configuration The device registry supports configuration of both an AMQP based endpoint exposing the Tenant, Device Registration and Credentials APIs as well as an HTTP based endpoint providing resources for managing tenants, registration information and credentials as defined by the Registry Management API. Both endpoints can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The registry will fail to start if none of the ports is configured properly.\nThe following sections apply to configuring both the AMQP and the HTTP endpoint. The environment variables to use for configuring the HTTP endpoint are the same as the ones for the AMQP endpoint, substituting _AMQP_ with _HTTP_, e.g. HONO_REGISTRY_HTTP_KEYPATH instead of HONO_REGISTRY_AMQP_KEYPATH.\nSecure Port Only The server needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_REGISTRY_AMQP_KEYSTOREPATH and the HONO_REGISTRY_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_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 port (5671 for AMQP and 8443 for HTTP). The port number can also be set explicitly using the HONO_REGISTRY_AMQP_PORT variable.\nThe HONO_REGISTRY_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 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).\nInsecure 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\nexplicitly setting HONO_REGISTRY_AMQP_INSECUREPORT to a valid port number, or implicitly configuring the default port (5672 for AMQP and 8080 for HTTP) to be used by setting HONO_REGISTRY_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if one of the insecure ports is set to the corresponding default secure port.\nThe HONO_REGISTRY_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The registry will then use arbitrary (unused) port numbers determined by the operating system during startup.\nAuthentication Service Connection Configuration The service requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.\nThe connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. The properties for configuring the client’s response caching will be ignored because Hono’s Authentication Service does not allow caching of responses.\nIn addition to the standard client configuration properties, the following properties are supported:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_JWKSENDPOINTPOLLINGINTERVAL\nhono.auth.jwksEndpointPollingInterval no PT5M The interval at which the JWK set should be retrieved from the Authentication service. The format used is the standard java.time.Duration format. HONO_AUTH_JWKSENDPOINTPORT\nhono.auth.jwksEndpointPort no 8088 The port of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_JWKSENDPOINTTLSENABLED\nhono.auth.jwksEndpointTlsEnabled no false Indicates if TLS should be used to retrieve the JWK set from the Authentication service. HONO_AUTH_JWKSENDPOINTURI\nhono.auth.jwksEndpointUri no /validating-keys The URI of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_VALIDATION_AUDIENCE\nhono.auth.validation.audience no - The value to expect to find in a token’s aud claim. If set, the token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_CERTPATH\nhono.auth.validation.certPath no - The absolute path to the PEM file containing the public key that the service should use for validating tokens issued by the Authentication service. Alternatively, a symmetric key can be used for validating tokens by setting the HONO_AUTH_VALIDATION_SHAREDSECRET variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. HONO_AUTH_VALIDATION_ISSUER\nhono.auth.validation.issuer yes https://hono.eclipse.org/auth-server The value to expect to find in a token’s iss claim. The token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_SHAREDSECRET\nhono.auth.validation.sharedSecret no - A string to derive a symmetric key from which will be used for validating tokens issued by the Authentication service. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the validation key using this variable, the Authentication service must be configured with the same key. Alternatively, an X.509 certificate can be used for validating tokens by setting the HONO_AUTH_VALIDATION_CERTPATH variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. Metrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\nEncrypting Secrets Hono’s CoAP protocol adapter supports authentication of devices during the DTLS handshake based on a pre-shared key. A pre-shared key is an arbitrary sequence of bytes which both the device as well as the protocol adapter need to present during the handshake in order to prove their identity. The Mongo DB based registry implementation supports managing these keys by means of PSK credentials which can be set for devices. By default, the bytes representing the key are stored as a base64 encoded string property of the credentials document. In order to better protect these keys from unintended disclosure, the registry can be configured to encrypt these keys before they are written to the database collection. During read operations the keys are then decrypted again before they are returned to an authorized client.\nIn order to activate this transparent encryption/decryption, the HONO_CREDENTIALS_SVC_ENCRYPTIONKEYFILE configuration variable needs to be set to the path to a YAML file containing the definition of the symmetric keys that should be used for encryption. The file is expected to have the following format:\ndefaultKey: 2 keys: - version: 1 key: hqHKBLV83LpCqzKpf8OvutbCs+O5wX5BPu3btWpEvXA= - version: 2 key: ge2L+MA9jLA8UiUJ4z5fUoK+Lgj2yddlL6EzYIBqb1Q= The file needs to contain at least all versions of the key that values in the database collection have been encrypted with. Otherwise the registry will not be able to decrypt these values during reading. The defaultKey property indicates the version of the key that should be used when encrypting values. Please refer to the CryptVault project for additional information regarding key rotation.\nMessaging Configuration The Device Registry uses a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to\nsend Device Provisioning Notification event messages to convey provisioning related changes regarding a device, to be received by downstream applications, send notification messages about changes to tenant/device/credentials data, to be processed by other Hono components. For the event messages a connection to a Apache Kafka cluster is used by default, if configured. If more than one kind of messaging is configured, the decision which one to use is done according to the Tenant Configuration.\nFor notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.\nAMQP 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 being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.\nKafka based Messaging Configuration The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.\nThe following table shows the prefixes to be used to individually configure the Kafka clients used by the Device Registry. 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.\nOS Environment Variable Prefix\nJava System Property Prefix Description HONO_KAFKA_EVENT_PRODUCERCONFIG_\nhono.kafka.event.producerConfig. Configures the Kafka producer that publishes event messages. HONO_KAFKA_NOTIFICATION_PRODUCERCONFIG_\nhono.kafka.notification.producerConfig. Configures the Kafka producer that publishes notification messages about changes to tenant/device/credentials data. Google Pub/Sub Messaging Configuration The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.\n",
    "description": "",
    "tags": null,
    "title": "MongoDB Based Device Registry Configuration",
    "uri": "/hono/docs/2.7/admin-guide/mongodb-device-registry-config/"
  },
  {
    "content": "The JDBC based Device Registry component provides an implementation of Eclipse Hono™’s Device Registration, Credentials and Tenant APIs. Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it. In addition to the above, this Device Registry also provides an implementation of Device Registry Management APIs for managing tenants, registration information and credentials of devices.\nThe registry is implemented as a Quarkus application, and it uses a JDBC compliant database to persist data. It provides the following features:\nBy default, supports H2 and PostgreSQL Supports different JDBC connections for read-only and read-write operations, to support read-only replicas Note: The provided container image contains only the H2 and PostgreSQL configuration and JDBC driver. While it is possible to use other JDBC compliant databases, database specific configuration and JDBC driver have to be provided by the user.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the JDBC based Device Registry.\nThe configuration uses the section ADAPTER for configurations of the protocol adapter facing services, and the section MANAGEMENT for management facing services. As adapters only require read-only operations, this can be used to direct adapters to services instances, which are backed by read-only replicas. Which can improve performance and availability.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_REGISTRY_AMQP_BINDADDRESS hono.registry.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_CERTPATH hono.registry.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_REGISTRY_AMQP_KEYPATH.\nAlternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_INSECUREPORT hono.registry.amqp.insecurePort no - The insecure port the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS hono.registry.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTENABLED hono.registry.amqp.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_AMQP_INSECUREPORT or the default AMQP port number (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_KEYPATH hono.registry.amqp.keyPath no - 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_REGISTRY_AMQP_CERTPATH. Alternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_KEYSTOREPASSWORD hono.registry.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_AMQP_KEYSTOREPATH hono.registry.amqp.keyStorePath no - 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_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_AMQP_NATIVETLSREQUIRED hono.registry.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_REGISTRY_AMQP_PORT hono.registry.amqp.port no 5671 The secure port that the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_SECUREPROTOCOLS hono.registry.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_AMQP_SUPPORTEDCIPHERSUITES hono.registry.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_HTTP_AUTHENTICATIONREQUIRED hono.registry.http.authenticationRequired no true If set to true the HTTP endpoint of the Device Registry requires clients to authenticate when connecting to the Device Registry. The JDBC based Device Registry currently supports basic authentication and the user credentials are to be stored in the database. For more information on how to manage users please refer to JDBC Auth Provider. HONO_REGISTRY_HTTP_BINDADDRESS hono.registry.http.bindAddress no 127.0.0.1 The IP address of the network interface that the secure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_CERTPATH hono.registry.http.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_REGISTRY_HTTP_KEYPATH.\nAlternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_DEVICEIDREGEX hono.registry.http.deviceIdRegex no ^[a-zA-Z0-9-_]+$ The regular expression to use to validate device ID. Please refer to the java pattern documentation. HONO_REGISTRY_HTTP_IDLETIMEOUT hono.registry.http.idleTimeout no 60 The idle timeout in seconds. A connection will timeout and be closed if no data is received or sent within the idle timeout period. A zero value means no timeout is used. HONO_REGISTRY_HTTP_INSECUREPORT hono.registry.http.insecurePort no - The insecure port the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTBINDADDRESS hono.registry.http.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTENABLED hono.registry.http.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_HTTP_INSECUREPORT or the default HTTP port number (8080) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_KEYPATH hono.registry.http.keyPath no - 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_REGISTRY_HTTP_CERTPATH. Alternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_KEYSTOREPASSWORD hono.registry.http.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_HTTP_KEYSTOREPATH hono.registry.http.keyStorePath no - 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_REGISTRY_HTTP_KEYPATH and HONO_REGISTRY_HTTP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_HTTP_MAXPAYLOADSIZE hono.registry.http.maxPayloadSize no 16000 The maximum size of an HTTP request body in bytes that is accepted by the registry. HONO_REGISTRY_HTTP_PORT hono.registry.http.port no 8443 The secure port that the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_SECUREPROTOCOLS hono.registry.http.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_HTTP_SUPPORTEDCIPHERSUITES hono.registry.http.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_HTTP_TENANTIDREGEX hono.registry.http.tenantIdRegex no ^[a-zA-Z0-9-_.]+$ The regular expression to use to validate tenant ID. Please refer to the java pattern documentation. HONO_REGISTRY_JDBC_ADAPTER_URL hono.registry.jdbc.adapter.url yes - The JDBC URL to the database. HONO_REGISTRY_JDBC_ADAPTER_DRIVERCLASS hono.registry.jdbc.adapter.driverClass no The default driver registered for the JDBC URL. The class name of the JDBC driver. HONO_REGISTRY_JDBC_ADAPTER_USERNAME hono.registry.jdbc.adapter.username no - The username used to access the database. HONO_REGISTRY_JDBC_ADAPTER_PASSWORD hono.registry.jdbc.adapter.password no - The password used to access the database. HONO_REGISTRY_JDBC_ADAPTER_MAXIMUMPOOLSIZE hono.registry.jdbc.adapter.maximumPoolSize no 15 The maximum size of the connection pool. HONO_REGISTRY_JDBC_ADAPTER_MINIMUMPOOLSIZE hono.registry.jdbc.adapter.minimumPoolSize no 3 The minimum size of the connection pool. HONO_REGISTRY_JDBC_ADAPTER_INITIALPOOLSIZE hono.registry.jdbc.adapter.initialPoolSize no 3 Number of connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. HONO_REGISTRY_JDBC_ADAPTER_MAXIMUMIDLETIME hono.registry.jdbc.adapter.maximumIdleTime no 3600 Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire. HONO_REGISTRY_JDBC_ADAPTER_MAXIMUMCONNECTIONTIME hono.registry.jdbc.adapter.maximumConnectionTime no 30 Maximum wait time in seconds to obtain a connection from the pool before the request fails. A value of zero disables the timeout. HONO_REGISTRY_JDBC_ADAPTER_VALIDATIONTIME hono.registry.jdbc.adapter.validationTime no 30 Interval, in seconds, in which connections in the pool are validated. A value of zero means connection validation is disabled. HONO_REGISTRY_JDBC_ADAPTER_LEAKTIME hono.registry.jdbc.adapter.leakTime no 60 Seconds after which a connection is considered to be leaking if it has not returned to the pool. A value of zero means connection leakage detection is disabled. HONO_REGISTRY_JDBC_ADAPTER_TABLENAME hono.registry.jdbc.adapter.tableName no - The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. HONO_REGISTRY_JDBC_MANAGEMENT_URL hono.registry.jdbc.management.url yes - The JDBC URL to the database. HONO_REGISTRY_JDBC_MANAGEMENT_DRIVERCLASS hono.registry.jdbc.management.driverClass no The default driver registered for the JDBC URL. The class name of the JDBC driver. HONO_REGISTRY_JDBC_MANAGEMENT_USERNAME hono.registry.jdbc.management.username no - The username used to access the database. HONO_REGISTRY_JDBC_MANAGEMENT_PASSWORD hono.registry.jdbc.management.password no - The password used to access the database. HONO_REGISTRY_JDBC_MANAGEMENT_MAXIMUMPOOLSIZE hono.registry.jdbc.management.maximumPoolSize no 15 The maximum size of the connection pool. HONO_REGISTRY_JDBC_MANAGEMENT_MINIMUMPOOLSIZE hono.registry.jdbc.management.minimumPoolSize no 3 The minimum size of the connection pool. HONO_REGISTRY_JDBC_MANAGEMENT_INITIALPOOLSIZE hono.registry.jdbc.management.initialPoolSize no 3 Number of connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. HONO_REGISTRY_JDBC_MANAGEMENT_MAXIMUMIDLETIME hono.registry.jdbc.management.maximumIdleTime no 3600 Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire. HONO_REGISTRY_JDBC_MANAGEMENT_MAXIMUMCONNECTIONTIME hono.registry.jdbc.management.maximumConnectionTime no 30 Maximum wait time in seconds to obtain a connection from the pool before the request fails. A value of zero disables the timeout. HONO_REGISTRY_JDBC_MANAGEMENT_VALIDATIONTIME hono.registry.jdbc.management.validationTime no 30 Interval, in seconds, in which connections in the pool are validated. A value of zero means connection validation is disabled. HONO_REGISTRY_JDBC_MANAGEMENT_LEAKTIME hono.registry.jdbc.management.leakTime no 60 Seconds after which a connection is considered to be leaking if it has not returned to the pool. A value of zero means connection leakage detection is disabled. HONO_REGISTRY_JDBC_MANAGEMENT_TABLENAME hono.registry.jdbc.management.tableName no - The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. HONO_REGISTRY_SVC_CREDENTIALSTTL hono.registry.svc.credentialsTtl no 1m The TTL for credentials responses. HONO_REGISTRY_SVC_HASHALGORITHMSWHITELIST hono.registry.svc.hashAlgorithmsWhitelist no empty An array of supported hashing algorithms to be used with the hashed-password type of credentials. When not set, all values will be accepted. HONO_REGISTRY_SVC_MAXBCRYPTCOSTFACTOR hono.registry.svc.maxBcryptCostFactor no 10 The maximum cost factor that is supported in password hashes using the BCrypt hash function. This limit is enforced by the device registry when adding or updating corresponding credentials. Increasing this number allows for potentially more secure password hashes to be used. However, the time required to compute the hash increases exponentially with the cost factor. HONO_REGISTRY_SVC_MAXDEVICESPERTENANT hono.registry.svc.maxDevicesPerTenant no -1 The number of devices that can be registered for each tenant. It is an error to set this property to a value \u003c -1. The value -1 indicates that no limit is set. HONO_REGISTRY_SVC_REGISTRATIONTTL hono.registry.svc.registrationTtl no 1m The TTL for registrations responses. HONO_REGISTRY_SVC_USERNAMEPATTERN hono.registry.svc.usernamePattern no ^[a-zA-Z0-9-_=\\\\.]+$ The regular expression to use for validating authentication identifiers (user names) of hashed-password credentials. HONO_TENANT_JDBC_ADAPTER_URL hono.tenant.jdbc.adapter.url yes - The JDBC URL to the database. HONO_TENANT_JDBC_ADAPTER_DRIVERCLASS hono.tenant.jdbc.adapter.driverClass no The default driver registered for the JDBC URL. The class name of the JDBC driver. HONO_TENANT_JDBC_ADAPTER_USERNAME hono.tenant.jdbc.adapter.username no - The username used to access the database. HONO_TENANT_JDBC_ADAPTER_PASSWORD hono.tenant.jdbc.adapter.password no - The password used to access the database. HONO_TENANT_JDBC_ADAPTER_MAXIMUMPOOLSIZE hono.tenant.jdbc.adapter.maximumPoolSize no 15 The maximum size of the connection pool. HONO_TENANT_JDBC_ADAPTER_MINIMUMPOOLSIZE hono.tenant.jdbc.adapter.minimumPoolSize no 3 The minimum size of the connection pool. HONO_TENANT_JDBC_ADAPTER_INITIALPOOLSIZE hono.tenant.jdbc.adapter.initialPoolSize no 3 Number of connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. HONO_TENANT_JDBC_ADAPTER_MAXIMUMIDLETIME hono.tenant.jdbc.adapter.maximumIdleTime no 3600 Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire. HONO_TENANT_JDBC_ADAPTER_MAXIMUMCONNECTIONTIME hono.tenant.jdbc.adapter.maximumConnectionTime no 30 Maximum wait time in seconds to obtain a connection from the pool before the request fails. A value of zero disables the timeout. HONO_TENANT_JDBC_ADAPTER_VALIDATIONTIME hono.tenant.jdbc.adapter.validationTime no 30 Interval, in seconds, in which connections in the pool are validated. A value of zero means connection validation is disabled. HONO_TENANT_JDBC_ADAPTER_LEAKTIME hono.tenant.jdbc.adapter.leakTime no 60 Seconds after which a connection is considered to be leaking if it has not returned to the pool. A value of zero means connection leakage detection is disabled. HONO_TENANT_JDBC_ADAPTER_TABLENAME hono.tenant.jdbc.adapter.tableName no - The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. HONO_TENANT_JDBC_MANAGEMENT_URL hono.tenant.jdbc.management.url yes - The JDBC URL to the database. HONO_TENANT_JDBC_MANAGEMENT_DRIVERCLASS hono.tenant.jdbc.management.driverClass no The default driver registered for the JDBC URL. The class name of the JDBC driver. HONO_TENANT_JDBC_MANAGEMENT_USERNAME hono.tenant.jdbc.management.username no - The username used to access the database. HONO_TENANT_JDBC_MANAGEMENT_PASSWORD hono.tenant.jdbc.management.password no - The password used to access the database. HONO_TENANT_JDBC_MANAGEMENT_MAXIMUMPOOLSIZE hono.tenant.jdbc.management.maximumPoolSize no 15 The maximum size of the connection pool. HONO_TENANT_JDBC_MANAGEMENT_MINIMUMPOOLSIZE hono.tenant.jdbc.management.minimumPoolSize no 3 The minimum size of the connection pool. HONO_TENANT_JDBC_MANAGEMENT_INITIALPOOLSIZE hono.tenant.jdbc.management.initialPoolSize no 3 Number of connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. HONO_TENANT_JDBC_MANAGEMENT_MAXIMUMIDLETIME hono.tenant.jdbc.management.maximumIdleTime no 3600 Seconds a connection can remain pooled but unused before being discarded. Zero means idle connections never expire. HONO_TENANT_JDBC_MANAGEMENT_MAXIMUMCONNECTIONTIME hono.tenant.jdbc.management.maximumConnectionTime no 30 Maximum wait time in seconds to obtain a connection from the pool before the request fails. A value of zero disables the timeout. HONO_TENANT_JDBC_MANAGEMENT_VALIDATIONTIME hono.tenant.jdbc.management.validationTime no 30 Interval, in seconds, in which connections in the pool are validated. A value of zero means connection validation is disabled. HONO_TENANT_JDBC_MANAGEMENT_LEAKTIME hono.tenant.jdbc.management.leakTime no 60 Seconds after which a connection is considered to be leaking if it has not returned to the pool. A value of zero means connection leakage detection is disabled. HONO_TENANT_JDBC_MANAGEMENT_TABLENAME hono.tenant.jdbc.management.tableName no - The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. HONO_TENANT_SVC_TENANTTTL hono.tenant.service.tenantTtl no 1m The TTL for tenant responses. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Monitoring Options Port Configuration The device registry supports configuration of both an AMQP based endpoint exposing the Tenant, Device Registration and Credentials APIs as well as an HTTP based endpoint providing resources for managing tenants, registration information and credentials as defined by the Registry Management API. Both endpoints can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The registry will fail to start if none of the ports is configured properly.\nThe following sections apply to configuring both the AMQP and the HTTP endpoint. The environment variables to use for configuring the HTTP endpoint are the same as the ones for the AMQP endpoint, substituting _AMQP_ with _HTTP_, e.g. HONO_REGISTRY_HTTP_KEYPATH instead of HONO_REGISTRY_AMQP_KEYPATH.\nSecure Port Only The server needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_REGISTRY_AMQP_KEYSTOREPATH and the HONO_REGISTRY_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_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 port (5671 for AMQP and 8443 for HTTP). The port number can also be set explicitly using the HONO_REGISTRY_AMQP_PORT variable.\nThe HONO_REGISTRY_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 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).\nInsecure 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\nexplicitly setting HONO_REGISTRY_AMQP_INSECUREPORT to a valid port number, or implicitly configuring the default port (5672 for AMQP and 8080 for HTTP) to be used by setting HONO_REGISTRY_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if one of the insecure ports is set to the corresponding default secure port.\nThe HONO_REGISTRY_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The registry will then use arbitrary (unused) port numbers determined by the operating system during startup.\nAuthentication Service Connection Configuration The service requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.\nThe connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. The properties for configuring the client’s response caching will be ignored because Hono’s Authentication Service does not allow caching of responses.\nIn addition to the standard client configuration properties, the following properties are supported:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_JWKSENDPOINTPOLLINGINTERVAL\nhono.auth.jwksEndpointPollingInterval no PT5M The interval at which the JWK set should be retrieved from the Authentication service. The format used is the standard java.time.Duration format. HONO_AUTH_JWKSENDPOINTPORT\nhono.auth.jwksEndpointPort no 8088 The port of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_JWKSENDPOINTTLSENABLED\nhono.auth.jwksEndpointTlsEnabled no false Indicates if TLS should be used to retrieve the JWK set from the Authentication service. HONO_AUTH_JWKSENDPOINTURI\nhono.auth.jwksEndpointUri no /validating-keys The URI of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_VALIDATION_AUDIENCE\nhono.auth.validation.audience no - The value to expect to find in a token’s aud claim. If set, the token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_CERTPATH\nhono.auth.validation.certPath no - The absolute path to the PEM file containing the public key that the service should use for validating tokens issued by the Authentication service. Alternatively, a symmetric key can be used for validating tokens by setting the HONO_AUTH_VALIDATION_SHAREDSECRET variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. HONO_AUTH_VALIDATION_ISSUER\nhono.auth.validation.issuer yes https://hono.eclipse.org/auth-server The value to expect to find in a token’s iss claim. The token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_SHAREDSECRET\nhono.auth.validation.sharedSecret no - A string to derive a symmetric key from which will be used for validating tokens issued by the Authentication service. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the validation key using this variable, the Authentication service must be configured with the same key. Alternatively, an X.509 certificate can be used for validating tokens by setting the HONO_AUTH_VALIDATION_CERTPATH variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. Metrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\nMessaging Configuration The Device Registry uses a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to\nsend Device Provisioning Notification event messages to convey provisioning related changes regarding a device, to be received by downstream applications, send notification messages about changes to tenant/device/credentials data, to be processed by other Hono components. For the event messages a connection to a Apache Kafka cluster is used by default, if configured. If more than one kind of messaging is configured, the decision which one to use is done according to the Tenant Configuration.\nFor notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.\nAMQP 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 being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.\nKafka based Messaging Configuration The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.\nThe following table shows the prefixes to be used to individually configure the Kafka clients used by the Device Registry. 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.\nOS Environment Variable Prefix\nJava System Property Prefix Description HONO_KAFKA_EVENT_PRODUCERCONFIG_\nhono.kafka.event.producerConfig. Configures the Kafka producer that publishes event messages. HONO_KAFKA_NOTIFICATION_PRODUCERCONFIG_\nhono.kafka.notification.producerConfig. Configures the Kafka producer that publishes notification messages about changes to tenant/device/credentials data. Google Pub/Sub Messaging Configuration The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.\n",
    "description": "",
    "tags": null,
    "title": "JDBC Based Device Registry Configuration",
    "uri": "/hono/docs/2.7/admin-guide/jdbc-device-registry-config/"
  },
  {
    "content": "The Command Router service provides an implementation of Eclipse Hono™’s Command Router API.\nProtocol Adapters use the Command Router API to supply information that the Command Router service component can use to route command \u0026 control messages to the particular protocol adapter instances that the target devices are connected to.\nThe 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.\nThe 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.\nInfo The Command Router had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the Command Router component.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of Verticle instances to deploy. If not set, one Verticle per processor core is deployed. HONO_COMMANDROUTER_AMQP_BINDADDRESS\nhono.commandRouter.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_COMMANDROUTER_AMQP_CERTPATH\nhono.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.\nAlternatively, 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\nhono.commandRouter.amqp.insecurePort no - The insecure port the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_COMMANDROUTER_AMQP_INSECUREPORTBINDADDRESS\nhono.commandRouter.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_COMMANDROUTER_AMQP_INSECUREPORTENABLED\nhono.commandRouter.amqp.insecurePortEnabled no false If set to true 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 (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_COMMANDROUTER_AMQP_KEYPATH\nhono.commandRouter.amqp.keyPath no - 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_KEYSTOREPASSWORD\nhono.commandRouter.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_COMMANDROUTER_AMQP_KEYSTOREPATH\nhono.commandRouter.amqp.keyStorePath no - 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 JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_COMMANDROUTER_AMQP_NATIVETLSREQUIRED\nhono.commandRouter.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_COMMANDROUTER_AMQP_PORT\nhono.commandRouter.amqp.port no 5671 The secure port that the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_COMMANDROUTER_AMQP_RECEIVERLINKCREDIT\nhono.commandRouter.amqp.receiverLinkCredit no 100 The number of credits to flow to a client connecting to the service’s AMQP endpoint. HONO_COMMANDROUTER_AMQP_SECUREPROTOCOLS\nhono.commandRouter.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_COMMANDROUTER_AMQP_SUPPORTEDCIPHERSUITES\nhono.commandRouter.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_COMMANDROUTER_SVC_KUBERNETESBASEDADAPTERINSTANCESTATUSSERVICEENABLED\nhono.commandRouter.svc.kubernetesBasedAdapterInstanceStatusServiceEnabled no true If set to true 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 \u0026 control messages to already terminated adapter instances. Needs to be set to false 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.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x 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\na 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.\nSecure Port Only The server needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_COMMANDROUTER_AMQP_KEYSTOREPATH and the HONO_COMMANDROUTER_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or 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_PORT variable.\nThe 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 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).\nInsecure 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\nexplicitly setting HONO_COMMANDROUTER_AMQP_INSECUREPORT to a valid port number, or by implicitly configuring the default AMQP port (5672) by simply setting HONO_COMMANDROUTER_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if HONO_COMMANDROUTER_AMQP_INSECUREPORT is set to the default secure AMQP port (5671).\nThe HONO_COMMANDROUTER_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_COMMANDROUTER_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The Command Router component will then use arbitrary (unused) port numbers determined by the operating system during startup.\nMessaging Configuration The Command Router component uses a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to\nreceive command \u0026 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 and Google Pub/Sub messaging), receive notification messages about changes to tenant/device/credentials data sent from the device registry. send an event message for Time until Disconnect Notification indicating the device readiness to receive commands. Command messages are received on each configured messaging system.\nFor notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.\nAMQP 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 and HONO_COMMAND being used as ${PREFIX}. The properties for configuring response caching can be ignored.\nKafka based Messaging Configuration The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.\nThe 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_KAFKA_COMMONCLIENTCONFIG_ and hono.kafka.commonClientConfig. respectively.\nOS Environment Variable Prefix\nJava System Property Prefix Description HONO_KAFKA_CLEANUP_ADMINCLIENTCONFIG_\nhono.kafka.cleanup.adminClientConfig. Configures the Kafka admin client that removes Hono internal topics. HONO_KAFKA_COMMAND_CONSUMERCONFIG_\nhono.kafka.command.consumerConfig. Configures the Kafka consumer that receives command messages. HONO_KAFKA_COMMANDINTERNAL_PRODUCERCONFIG_\nhono.kafka.commandInternal.producerConfig. Configures the Kafka producer that publishes command messages to Hono internal topics. HONO_KAFKA_COMMANDRESPONSE_PRODUCERCONFIG_\nhono.kafka.commandResponse.producerConfig. Configures the Kafka producer that publishes command response messages. HONO_KAFKA_NOTIFICATION_CONSUMERCONFIG_\nhono.kafka.notification.consumerConfig. Configures the Kafka consumer that receives notification messages about changes to tenant/device/credentials data. Google Pub/Sub Messaging Configuration The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.\nTenant 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.\nThe 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.\nThe 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.\nDevice 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.\nThe connection to the Device Registration Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_REGISTRATION.\nThe 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.\nNote 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.\nData 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.\nThe following table provides an overview of the configuration variables and corresponding command line options for configuring the common aspects of the service:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_COMMANDROUTER_CACHE_COMMON_CACHENAME\nhono.commandRouter.cache.common.cacheName no command-router The name of the cache HONO_COMMANDROUTER_CACHE_COMMON_CHECKKEY\nhono.commandRouter.cache.common.checkKey no KEY_CONNECTION_CHECK The key used to check the health of the cache. This is only used in case of a remote cache. HONO_COMMANDROUTER_CACHE_COMMON_CHECKVALUE\nhono.commandRouter.cache.common.checkValue no VALUE_CONNECTION_CHECK The 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_CACHE_REMOTE_SERVERLIST configuration variable. If the variable has a non empty value, a remote cache is configured. Otherwise, an embedded cache is configured.\nRemote cache The following table provides an overview of the configuration variables and corresponding system properties for configuring the connection to the data grid:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_COMMANDROUTER_CACHE_REMOTE_SERVERLIST\nhono.commandRouter.cache.remote.serverList yes - A list of remote servers in the form: host1[:port][;host2[:port]]..... HONO_COMMANDROUTER_CACHE_REMOTE_AUTHSERVERNAME\nhono.commandRouter.cache.remote.authServerName yes - The server name to indicate in the SASL handshake when authenticating to the server. HONO_COMMANDROUTER_CACHE_REMOTE_AUTHREALM\nhono.commandRouter.cache.remote.authRealm yes - The authentication realm for the SASL handshake when authenticating to the server. HONO_COMMANDROUTER_CACHE_REMOTE_AUTHUSERNAME\nhono.commandRouter.cache.remote.authUsername yes - The username to use for authenticating to the server. HONO_COMMANDROUTER_CACHE_REMOTE_AUTHPASSWORD\nhono.commandRouter.cache.remote.authPassword yes - The password to use for authenticating to the server. HONO_COMMANDROUTER_CACHE_REMOTE_SASLMECHANISM\nhono.commandRouter.cache.remote.saslMechanism yes - The SASL mechanism to use for authenticating to the server. HONO_COMMANDROUTER_CACHE_REMOTE_CLUSTER_[*]\nhono.commandRouter.cache.remote.cluster.[*] no - Alternate cluster definition. Example: Property: hono.commandRouter.cache.remote.cluster.siteA, value: hostA1:11222;hostA2:11223. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_EXHAUSTEDACTION\nhono.commandRouter.cache.remote.connectionPool.exhaustedAction no WAIT Specifies what happens when asking for a connection from a server’s pool, and that pool is exhausted. Valid values are WAIT, CREATE_NEW and EXCEPTION. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_MAXACTIVE\nhono.commandRouter.cache.remote.connectionPool.maxActive no -1 (no limit) Maximum number of connections per server. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_MAXPENDINGREQUESTS\nhono.commandRouter.cache.remote.connectionPool.maxPendingRequests no -1 (no limit) Specifies the maximum number of requests sent over a single connection at one instant. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_MAXWAIT\nhono.commandRouter.cache.remote.connectionPool.maxWait no -1 (no limit) Time to wait in milliseconds for a connection to become available if exhaustedAction is WAIT. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_MINEVICTABLEIDLETIME\nhono.commandRouter.cache.remote.connectionPool.minEvictableIdleTime no -1 (no limit) Minimum amount of time that an connection may sit idle in the pool. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTIONPOOL_MINIDLE\nhono.commandRouter.cache.remote.connectionPool.minIdle no -1 (no limit) Minimum number of idle connections (per server) that should always be available. HONO_COMMANDROUTER_CACHE_REMOTE_CONNECTTIMEOUT\nhono.commandRouter.cache.remote.connectTimeout no 60000 The timeout for connections in milliseconds. HONO_COMMANDROUTER_CACHE_REMOTE_DEFAULTEXECUTORFACTORY_POOLSIZE\nhono.commandRouter.cache.remote.defaultExecutorFactory.poolSize no 99 Size of the thread pool. HONO_COMMANDROUTER_CACHE_REMOTE_DEFAULTEXECUTORFACTORY_THREADNAMEPREFIX\nhono.commandRouter.cache.remote.defaultExecutorFactory.threadnamePrefix no HotRod-client-async-pool Prefix for the default executor thread names. HONO_COMMANDROUTER_CACHE_REMOTE_DEFAULTEXECUTORFACTORY_THREADNAMESUFFIX\nhono.commandRouter.cache.remote.defaultExecutorFactory.threadnameSuffix no - Suffix for the default executor thread names. HONO_COMMANDROUTER_CACHE_REMOTE_KEYALIAS\nhono.commandRouter.cache.remote.keyAlias no - The alias of the key to use, in case the keyStore contains multiple certificates. HONO_COMMANDROUTER_CACHE_REMOTE_KEYSTORECERTIFICATEPASSWORD\nhono.commandRouter.cache.remote.keyStoreCertificatePassword no - The certificate password in the keystore. HONO_COMMANDROUTER_CACHE_REMOTE_KEYSTOREFILENAME\nhono.commandRouter.cache.remote.keyStoreFileName no - The filename of a keystore to use when using client certificate authentication. HONO_COMMANDROUTER_CACHE_REMOTE_KEYSTOREPASSWORD\nhono.commandRouter.cache.remote.keyStorePassword no - The keystore password. HONO_COMMANDROUTER_CACHE_REMOTE_KEYSTORETYPE\nhono.commandRouter.cache.remote.keyStoreType no JKS The keystore type. HONO_COMMANDROUTER_CACHE_REMOTE_SASLPROPERTIES_[*]\nhono.commandRouter.cache.remote.saslProperties.[*] no - A SASL property (specific to the used SASL mechanism). HONO_COMMANDROUTER_CACHE_REMOTE_SOCKETTIMEOUT\nhono.commandRouter.cache.remote.socketTimeout no 60000 The timeout for socket read/writes in milliseconds. HONO_COMMANDROUTER_CACHE_REMOTE_SSLCIPHERS\nhono.commandRouter.cache.remote.sslCiphers no - 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_COMMANDROUTER_CACHE_REMOTE_SSLPROTOCOL\nhono.commandRouter.cache.remote.sslProtocol no - The SSL protocol to use (e.g. TLSv1.2). HONO_COMMANDROUTER_CACHE_REMOTE_TRUSTSTOREFILENAME\nhono.commandRouter.cache.remote.trustStoreFileName no - The path of the trust store. HONO_COMMANDROUTER_CACHE_REMOTE_TRUSTSTOREPASSWORD\nhono.commandRouter.cache.remote.trustStorePassword no - The password of the trust store. HONO_COMMANDROUTER_CACHE_REMOTE_TRUSTSTORETYPE\nhono.commandRouter.cache.remote.trustStoreType no JKS The type of the trust store. Valid values are JKS, JCEKS, PCKS12 and PEM. HONO_COMMANDROUTER_CACHE_REMOTE_USESSL\nhono.commandRouter.cache.remote.useSSL no false Enable TLS (implicitly enabled if a trust store is set). See also the Infinispan Hotrod client documentation.\nEmbedded cache The following table provides an overview of the configuration variables and corresponding system properties for configuring the embedded cache:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_COMMANDROUTER_CACHE_EMBEDDED_CONFIGURATIONFILE\nhono.commandRouter.cache.embedded.configurationFile yes - 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.\nThe connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. The properties for configuring the client’s response caching will be ignored because Hono’s Authentication Service does not allow caching of responses.\nIn addition to the standard client configuration properties, the following properties are supported:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_JWKSENDPOINTPOLLINGINTERVAL\nhono.auth.jwksEndpointPollingInterval no PT5M The interval at which the JWK set should be retrieved from the Authentication service. The format used is the standard java.time.Duration format. HONO_AUTH_JWKSENDPOINTPORT\nhono.auth.jwksEndpointPort no 8088 The port of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_JWKSENDPOINTTLSENABLED\nhono.auth.jwksEndpointTlsEnabled no false Indicates if TLS should be used to retrieve the JWK set from the Authentication service. HONO_AUTH_JWKSENDPOINTURI\nhono.auth.jwksEndpointUri no /validating-keys The URI of the Authentication service’s HTTP endpoint to retrieve the JWK set from. HONO_AUTH_VALIDATION_AUDIENCE\nhono.auth.validation.audience no - The value to expect to find in a token’s aud claim. If set, the token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_CERTPATH\nhono.auth.validation.certPath no - The absolute path to the PEM file containing the public key that the service should use for validating tokens issued by the Authentication service. Alternatively, a symmetric key can be used for validating tokens by setting the HONO_AUTH_VALIDATION_SHAREDSECRET variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. HONO_AUTH_VALIDATION_ISSUER\nhono.auth.validation.issuer yes https://hono.eclipse.org/auth-server The value to expect to find in a token’s iss claim. The token will not be trusted if the value in the claim does not match the value configured using this property. HONO_AUTH_VALIDATION_SHAREDSECRET\nhono.auth.validation.sharedSecret no - A string to derive a symmetric key from which will be used for validating tokens issued by the Authentication service. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the validation key using this variable, the Authentication service must be configured with the same key. Alternatively, an X.509 certificate can be used for validating tokens by setting the HONO_AUTH_VALIDATION_CERTPATH variable. If none of these variables is set, the service will try to retrieve a JWK set containing the key(s) from the Authentication server. Metrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\n",
    "description": "",
    "tags": null,
    "title": "Configuring the Command Router Service",
    "uri": "/hono/docs/2.7/admin-guide/command-router-config/"
  },
  {
    "content": "The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nThe 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.\nInfo The HTTP adapter had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the HTTP adapter.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. HONO_HTTP_AUTHENTICATIONREQUIRED\nhono.http.authenticationRequired no true If set to true the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured Credentials Service. Devices that have failed to authenticate are not allowed to publish any data. HONO_HTTP_BINDADDRESS\nhono.http.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_HTTP_CERTPATH\nhono.http.certPath no - The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_HTTP_KEYPATH.\nAlternatively, the HONO_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_HTTP_DEFAULTSENABLED\nhono.http.defaultsEnabled no true If set to true the protocol adapter uses default values registered for a device and/or its tenant to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds such default values as Kafka record headers or AMQP 1.0 message (application) properties before the message is sent downstream. HONO_HTTP_IDLETIMEOUT hono.http.idleTimeout no 75 The idle timeout in seconds. A connection will timeout and be closed if no data is received or sent within the idle timeout period. A zero value means no timeout is used.\nThe value configured here has to be 25 % higher than the maximum hono-ttd HTTP request header or query parameter (ttd for time till disconnect) value that should be supported. See the corresponding max-ttd tenant configuration property in the HTTP Adapter User Guide. HONO_HTTP_INSECUREPORT\nhono.http.insecurePort no - The insecure port the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_HTTP_INSECUREPORTBINDADDRESS\nhono.http.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_HTTP_INSECUREPORTENABLED\nhono.http.insecurePortEnabled no false If set to true the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via HONO_HTTP_INSECUREPORT or the default port number (8080) if not set explicitly.\nSee Port Configuration below for details. HONO_HTTP_KEYPATH\nhono.http.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_HTTP_CERTPATH. Alternatively, the HONO_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_HTTP_KEYSTOREPASSWORD\nhono.http.keyStorePassword no - The password required to read the contents of the key store. HONO_HTTP_KEYSTOREPATH\nhono.http.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the protocol adapter should use for authenticating to clients. Either this option or the HONO_HTTP_KEYPATH and HONO_HTTP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_HTTP_SNI\nhono.http.sni no false Set whether the server supports Server Name Indication. By default, the server will not support SNI and the option is false. However, if set to true then the key store format , HONO_HTTP_KEYSTOREPATH, should be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_HTTP_NATIVETLSREQUIRED\nhono.http.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_HTTP_MAXPAYLOADSIZE\nhono.http.maxPayloadSize no 2048 The maximum allowed size of an incoming HTTP request’s body in bytes. Requests with a larger body size are rejected with a 413 Request entity too large response. HONO_HTTP_PORT\nhono.http.port no 8443 The secure port that the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_HTTP_REALM\nhono.http.realm no Hono The name of the realm that unauthenticated devices are prompted to provide credentials for. The realm is used in the WWW-Authenticate header returned to devices in response to unauthenticated requests. HONO_HTTP_SECUREPROTOCOLS\nhono.http.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_AMQP_SUPPORTEDCIPHERSUITES\nhono.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that the adapter may use in TLS sessions with devices. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_HTTP_TENANTIDLETIMEOUT\nhono.http.tenantIdleTimeout no PT0S The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. 2h for 2 hours. See the java.time.Duration documentation for an explanation of the format. The leading PT can be omitted if only specifying hours, minutes or seconds. The value 0s (or PT0S) disables the timeout. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon 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\na 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.\nSecure Port Only The protocol adapter needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_HTTP_KEYSTOREPATH and the HONO_HTTP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or 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.\nThe 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).\nInsecure 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\nexplicitly 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).\nThe 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.\nSetting 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).\nDual 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.\nEphemeral 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.\n",
    "description": "",
    "tags": null,
    "title": "HTTP Adapter Configuration",
    "uri": "/hono/docs/2.7/admin-guide/http-adapter-config/"
  },
  {
    "content": "The MQTT protocol adapter exposes an MQTT topic hierarchy for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nThe 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.\nInfo The MQTT adapter had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the MQTT adapter.\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. HONO_CONNECTION_EVENTS_PRODUCER\nhono.connectionEvents.producer no logging The implementation of connection events producer which is to be used. This may be logging or events.\nSee Connection Events HONO_MQTT_AUTHENTICATIONREQUIRED\nhono.mqtt.authenticationRequired no true If set to true the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured Credentials Service. Devices that have failed to authenticate are not allowed to publish any data. HONO_MQTT_BINDADDRESS\nhono.mqtt.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_MQTT_CERTPATH\nhono.mqtt.certPath no - The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_MQTT_KEYPATH.\nAlternatively, the HONO_MQTT_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_MQTT_SENDMESSAGETODEVICETIMEOUT\nhono.mqtt.sendMessageToDeviceTimeout no 1000 The amount of time (milliseconds) after which the sending of a command or an error message to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. HONO_MQTT_DEFAULTSENABLED\nhono.mqtt.defaultsEnabled no true If set to true the protocol adapter uses default values registered for a device and/or its tenant to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds such default values as Kafka record headers or AMQP 1.0 message (application) properties before the message is sent downstream. HONO_MQTT_GCHEAPPERCENTAGE\nhono.mqtt.gcHeapPercentage no 25 The share of heap memory that should not be used by the live-data set but should be left to be used by the garbage collector. This property is used for determining the maximum number of (device) connections that the adapter should support. The value may be adapted to better reflect the characteristics of the type of garbage collector being used by the JVM and the total amount of memory available to the JVM. HONO_MQTT_INSECUREPORTBINDADDRESS\nhono.mqtt.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_MQTT_INSECUREPORTENABLED\nhono.mqtt.insecurePortEnabled no false If set to true the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via HONO_MQTT_INSECUREPORT or the default MQTT port number (1883) if not set explicitly.\nSee Port Configuration below for details. HONO_MQTT_KEYPATH\nhono.mqtt.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_MQTT_CERTPATH. Alternatively, the HONO_MQTT_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_MQTT_KEYSTOREPASSWORD\nhono.mqtt.keyStorePassword no - The password required to read the contents of the key store. HONO_MQTT_KEYSTOREPATH\nhono.mqtt.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the protocol adapter should use for authenticating to clients. Either this option or the HONO_MQTT_KEYPATH and HONO_MQTT_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_MQTT_SNI\nhono.mqtt.sni no false Set whether the server supports Server Name Indication. By default, the server will not support SNI and the option is false. However, if set to true then the key store format , HONO_MQTT_KEYSTOREPATH, should be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_MQTT_MAXCONNECTIONS\nhono.mqtt.maxConnections no 0 The maximum number of concurrent connections that the protocol adapter should accept. If not set (or set to 0), the protocol adapter determines a reasonable value based on the available resources like memory and CPU. HONO_MQTT_MAXPAYLOADSIZE\nhono.mqtt.maxPayloadSize no 2048 The maximum allowed size of an incoming MQTT message’s payload in bytes. When a client sends a message with a larger payload, the message is discarded and the connection to the client gets closed. HONO_MQTT_NATIVETLSREQUIRED\nhono.mqtt.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_MQTT_PORT\nhono.mqtt.port no 8883 The secure port that the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_MQTT_SECUREPROTOCOLS\nhono.mqtt.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_MQTT_SUPPORTEDCIPHERSUITES\nhono.mqtt.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that the adapter may use in TLS sessions with devices. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_MQTT_TENANTIDLETIMEOUT\nhono.mqtt.tenantIdleTimeout no PT0S The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. 2h for 2 hours. See the java.time.Duration documentation for an explanation of the format. The leading PT can be omitted if only specifying hours, minutes or seconds. The value 0s (or PT0S) disables the timeout. The variables only need to be set if the default values do not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Common Protocol Adapter Options Monitoring Options Port Configuration The MQTT protocol adapter can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The MQTT protocol adapter will fail to start if none of the ports is configured properly.\nSecure Port Only The protocol adapter needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\neither setting the HONO_MQTT_KEYSTOREPATH and the HONO_MQTT_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_MQTT_KEYPATH and HONO_MQTT_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 MQTT port 8883. The port number can also be set explicitly using the HONO_MQTT_PORT variable.\nThe HONO_MQTT_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).\nInsecure 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\nexplicitly setting HONO_MQTT_INSECUREPORT to a valid port number, or by implicitly configuring the default MQTT port (1883) by simply setting HONO_MQTT_INSECUREPORTENABLED to true. The protocol adapter issues a warning on the console if HONO_MQTT_INSECUREPORT is set to the default secure MQTT port (8883).\nThe HONO_MQTT_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.\nSetting 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).\nDual 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.\nEphemeral 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.\nCustom Message Mapping This protocol adapter supports transformation of messages that have been uploaded by devices before forwarding them to downstream consumers. This message mapping can be used to overwrite the deviceID, add additional properties and change the payload.\nInfo This is an experimental feature. The names of the configuration properties, potential values and the overall functionality are therefore subject to change without prior notice.\nThe following table provides an overview of the configuration variables and corresponding system properties for configuring the external service endpoint(s) for transforming messages:\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_MQTT_MAPPERENDPOINTS_\u003cmapperName\u003e_HOST\nhono.mqtt.mapperEndpoints.\u003cmapperName\u003e.host no - The host name or IP address of the service to invoke for transforming uploaded messages. The \u003cmapperName\u003e needs to contain the service name as set in the mapper property of the device’s registration information. HONO_MQTT_MAPPERENDPOINTS_\u003cmapperName\u003e_PORT\nhono.mqtt.mapperEndpoints.\u003cmapperName\u003e.port no - The port of the service to invoke for transforming uploaded messages. The \u003cmapperName\u003e needs to contain the service name as set in the mapper property of the device’s registration information. HONO_MQTT_MAPPERENDPOINTS_\u003cmapperName\u003e_URI\nhono.mqtt.mapperEndpoints.\u003cmapperName\u003e.uri no - The URI of the service to invoke for transforming uploaded messages. The \u003cmapperName\u003e needs to contain the service name as set in the mapper property of the device’s registration information. Implementation An implementation of the mapper needs to be provided. Following data will be provided to the mapper:\nHTTP headers: orig_address content-type tenant_id all strings configured during registration Body The payload of the message is provided in the body of the mapping request When the mapper responds successfully(=200), the adapter will map the returning values as follows:\nThe header with key device_id will overwrite the current deviceID. The remaining HTTP headers will be added to the downstream message as additional properties. The returned body will be used to replace the payload. ",
    "description": "",
    "tags": null,
    "title": "MQTT Adapter Configuration",
    "uri": "/hono/docs/2.7/admin-guide/mqtt-adapter-config/"
  },
  {
    "content": "The AMQP protocol adapter exposes AMQP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nThe 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.\nInfo The AMQP adapter had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the AMQP adapter.\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_AMQP_AUTHENTICATIONREQUIRED\nhono.amqp.authenticationRequired no true If set to true the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured Credentials Service. Devices that have failed to authenticate are not allowed to publish any data. HONO_AMQP_BINDADDRESS\nhono.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_AMQP_CERTPATH\nhono.amqp.certPath no - The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_AMQP_KEYPATH.\nAlternatively, the HONO_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_AMQP_DEFAULTSENABLED\nhono.amqp.defaultsEnabled no true If set to true the protocol adapter uses default values registered for a device and/or its tenant to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds such default values as Kafka record headers or AMQP 1.0 message (application) properties before the message is sent downstream. HONO_AMQP_GCHEAPPERCENTAGE\nhono.amqp.gcHeapPercentage no 25 The share of heap memory that should not be used by the live-data set but should be left to be used by the garbage collector. This property is used for determining the maximum number of (device) connections that the adapter should support. The value may be adapted to better reflect the characteristics of the type of garbage collector being used by the JVM and the total amount of memory available to the JVM. HONO_AMQP_IDLETIMEOUT\nhono.amqp.idleTimeout no 60000 The time interval (milliseconds) to wait for incoming traffic from a device before the connection should be considered stale and thus be closed. Setting this property to 0 prevents the adapter from detecting and closing stale connections. HONO_AMQP_SEND_MESSAGE_TO_DEVICE_TIMEOUT\nhono.amqp.sendMessageToDeviceTimeout no 1000 The time interval (milliseconds) to wait for a device to acknowledge receiving a (command) message before the AMQP link used for sending the message will be closed. Setting this property to 0 means the adapter waits indefinitely for a device to acknowledge receiving the message. HONO_AMQP_INSECUREPORTBINDADDRESS\nhono.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_AMQP_INSECUREPORT\nhono.amqp.insecurePort no 5672 The port number that the protocol adapter should listen on for insecure connections.\nSee Port Configuration below for details. HONO_AMQP_INSECUREPORTENABLED\nhono.amqp.insecurePortEnabled no false If set to true the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via HONO_AMQP_INSECUREPORT or the default AMQP port number (1883) if not set explicitly.\nSee Port Configuration below for details. HONO_AMQP_KEYPATH\nhono.amqp.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_AMQP_CERTPATH. Alternatively, the HONO_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_AMQP_KEYSTOREPASSWORD\nhono.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_AMQP_KEYSTOREPATH\nhono.amqp.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the protocol adapter should use for authenticating to clients. Either this option or the HONO_AMQP_KEYPATH and HONO_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_AMQP_SNI\nhono.amqp.sni no false Set whether the server supports Server Name Indication. By default, the server will not support SNI and the option is false. However, if set to true then the key store format, HONO_AMQP_KEYSTOREPATH, should be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_AMQP_MAXCONNECTIONS\nhono.amqp.maxConnections no 0 The maximum number of concurrent connections that the protocol adapter should accept. If not set (or set to 0), the protocol adapter determines a reasonable value based on the available resources like memory and CPU. HONO_AMQP_MAXFRAMESIZE\nhono.amqp.maxFrameSize no 16384 The maximum size (in bytes) of a single AMQP frame that the adapter should accept from the device. When a device sends a bigger frame, the connection will be closed. HONO_AMQP_MAXPAYLOADSIZE\nhono.amqp.maxPayloadSize no 2048 The maximum allowed size of an incoming AMQP message in bytes. When a client sends a message with a larger payload, the message is discarded and the link to the client is closed. HONO_AMQP_MAX_SESSION_FRAMES\nhono.amqp.maxSessionFrames no 30 The maximum number of AMQP transfer frames for sessions created on this connection. This is the number of transfer frames that may simultaneously be in flight for all links in the session. HONO_AMQP_NATIVETLSREQUIRED\nhono.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_AMQP_PORT\nhono.amqp.port no 5671 The secure port that the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_AMQP_SECUREPROTOCOLS\nhono.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_AMQP_SUPPORTEDCIPHERSUITES\nhono.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that the adapter may use in TLS sessions with devices. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_AMQP_TENANTIDLETIMEOUT\nhono.amqp.tenantIdleTimeout no PT0S The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. 2h for 2 hours. See the java.time.Duration documentation for an explanation of the format. The leading PT can be omitted if only specifying hours, minutes or seconds. The value 0s (or PT0S) disables the timeout. HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. The variables only need to be set if the default values do not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Common Protocol Adapter Options Monitoring Options Port Configuration The AMQP protocol adapter can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The AMQP protocol adapter will fail to start if none of the ports is configured properly.\nSecure Port Only The protocol adapter needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\neither setting the HONO_AMQP_KEYSTOREPATH and the HONO_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_AMQP_KEYPATH and HONO_AMQP_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 5671. The port number can also be set explicitly using the HONO_AMQP_PORT variable.\nThe HONO_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 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).\nInsecure 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\nexplicitly setting HONO_AMQP_INSECUREPORT to a valid port number, or by implicitly configuring the default adapter port (5672) by simply setting HONO_AMQP_INSECUREPORTENABLED to true. The protocol adapter issues a warning on the console if HONO_AMQP_INSECUREPORT is set to the default secure port (5671) used by the adapter for secure connections.\nThe HONO_AMQP_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.\nSetting 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).\nDual 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.\nEphemeral 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.\n",
    "description": "",
    "tags": null,
    "title": "AMQP Adapter Configuration",
    "uri": "/hono/docs/2.7/admin-guide/amqp-adapter-config/"
  },
  {
    "content": "The CoAP protocol adapter exposes CoAP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nThe adapter is implemented as a Quarkus application using Eclipse Californium™ for implementing the CoAP protocol handling. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.\nInfo The CoAP adapter had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the CoAP adapter.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. HONO_COAP_AUTHENTICATIONREQUIRED\nhono.coap.authenticationRequired no true If set to true the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured Credentials Service. Devices that fail to authenticate are not allowed to connect to the adapter. HONO_COAP_BINDADDRESS\nhono.coap.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_COAP_BLOCKWISESTATUSLIFETIME\nhono.coap.blockwiseStatusLifetime no 300000 The blockwise status lifetime in milliseconds. If no new blockwise request is received within that lifetime, blockwise status will be removed and the related resources are freed. HONO_COAP_CERTPATH\nhono.coap.certPath no - The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_COAP_KEYPATH.\nAlternatively, the HONO_COAP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. Note that the CoAP adapter supports ECDSA based keys only. HONO_COAP_COAPTHREADS\nhono.coap.coapThreads no 2 The number of threads to use for processing CoAP message exchanges at the protocol layer. HONO_COAP_CONNECTORTHREADS\nhono.coap.connectorThreads no 2 The number of threads to use for receiving/sending UDP packets. The connector will start the given number of threads for each direction, outbound (sending) as well as inbound (receiving). HONO_COAP_DTLSTHREADS\nhono.coap.dtlsThreads no 32 The number of threads to use for processing DTLS message exchanges at the connection layer. HONO_COAP_DTLSRETRANSMISSIONTIMEOUT\nhono.coap.dtlsRetransmissionTimeout no 2000 The timeout in milliseconds for DTLS retransmissions. HONO_COAP_DEFAULTSENABLED\nhono.coap.defaultsEnabled no true If set to true the protocol adapter uses default values registered for a device and/or its tenant to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds such default values as Kafka record headers or AMQP 1.0 message (application) properties before the message is sent downstream. HONO_COAP_EXCHANGELIFETIME\nhono.coap.exchangeLifetime no 247000 The exchange lifetime in milliseconds. According RFC 7252, that value is 247s. Such a large time requires also a huge amount of heap. That time includes a processing time of 100s and retransmissions of CON messages. Therefore a practical value could be much smaller. HONO_COAP_GCHEAPPERCENTAGE\nhono.coap.gcHeapPercentage no 25 The share of heap memory that should not be used by the live-data set but should be left to be used by the garbage collector. This property is used for determining the maximum number of (device) connections that the adapter should support. The value may be adapted to better reflect the characteristics of the type of garbage collector being used by the JVM and the total amount of memory available to the JVM. HONO_COAP_INSECURENETWORKCONFIG\nhono.coap.insecureNetworkConfig no - The absolute path to a Californium properties file containing network configuration properties that should be used for the insecure CoAP port. If not set, Californium’s default properties will be used. If the file is not available, not readable or malformed, the adapter will fail to start. HONO_COAP_INSECUREPORT\nhono.coap.insecurePort no - The insecure port the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_COAP_INSECUREPORTBINDADDRESS\nhono.coap.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_COAP_INSECUREPORTENABLED\nhono.coap.insecurePortEnabled no false If set to true the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via HONO_COAP_INSECUREPORT or the default port number (5683) if not set explicitly.\nSee Port Configuration below for details. HONO_COAP_KEYPATH\nhono.coap.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_COAP_CERTPATH. Alternatively, the HONO_COAP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. Note that the CoAP adapter supports ECDSA based keys only. HONO_COAP_KEYSTOREPASSWORD\nhono.coap.keyStorePassword no - The password required to read the contents of the key store. HONO_COAP_KEYSTOREPATH\nhono.coap.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the protocol adapter should use for authenticating to clients. Either this option or the HONO_COAP_KEYPATH and HONO_COAP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. Note that the CoAP adapter supports ECDSA based keys only. HONO_COAP_MAXCONNECTIONS\nhono.coap.maxConnections no 0 The maximum number of concurrent DTLS connections that the protocol adapter should accept. If set to 0, the protocol adapter determines a reasonable value based on the available resources like memory and CPU. HONO_COAP_MAXPAYLOADSIZE\nhono.coap.maxPayloadSize no 2048 The maximum allowed size of an incoming CoAP request’s body in bytes. Requests with a larger body size are rejected with a 4.13 Request entity too large response. HONO_COAP_MESSAGEOFFLOADINGENABLED\nhono.coap.messageOffloadingEnabled no true Enables to clear payload and serialized messages kept for deduplication in order to reduce the heap consumption. Experimental. HONO_COAP_NETWORKCONFIG\nhono.coap.networkConfig no - The absolute path to a Californium properties file containing network configuration properties that should be used for the insecure and secure CoAP port. If not set, Californium’s default properties will be used. Values may be overwritten using the specific HONO_COAP_INSECURENETWORKCONFIG or HONO_COAP_SECURENETWORKCONFIG. If the file is not available, not readable or malformed, the adapter will fail to start. HONO_COAP_PORT\nhono.coap.port no - The secure port that the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_COAP_SECURENETWORKCONFIG\nhono.coap.secureNetworkConfig no - The absolute path to a Californium properties file containing network configuration properties that should be used for the secure CoAP port. If not set, Californium’s default properties will be used. If the file is not available, not readable or malformed, the adapter will fail to start. HONO_COAP_TENANTIDLETIMEOUT\nhono.coap.tenantIdleTimeout no PT0S The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. 2h for 2 hours. See the java.time.Duration documentation for an explanation of the format. The leading PT can be omitted if only specifying hours, minutes or seconds. The value 0s (or PT0S) disables the timeout. HONO_COAP_TIMEOUTTOACK\nhono.coap.timeoutToAck no 500 Timeout in milliseconds to send an ACK for a CoAP CON request. If the response is available before that timeout, a more efficient piggybacked response is used. If the timeout is reached without having received a response, an empty ACK is sent back to the client and the response is sent in a separate CON once it becomes available. Special values: -1 means to always piggyback the response in an ACK and never send a separate CON; 0 means to always send an ACK immediately and include the response in a separate CON. The variables only need to be set if the default value needs to be changed.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Common Protocol Adapter Options Monitoring Options Port Configuration The CoAP protocol adapter can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The CoAP protocol adapter will fail to start if none of the ports is configured properly.\nSecure Port Only The protocol adapter opens a DTLS secured port if any of the following criteria are met\nThe HONO_COAP_KEYSTOREPATH and HONO_COAP_KEYSTOREPASSWORD environment variables are set in order to load a key and certificate from a password protected key store or the HONO_COAP_KEYPATH and HONO_COAP_CERTPATH environment variables are set in order to load a key and certificate from two separate PEM files in PKCS8 format or the HONO_COAP_PORT environment variable is set to a valid port number. When starting up, the protocol adapter will bind a DTLS secured UDP socket to the configured port. If the port is not set explicitly, the default CoAP secure port 5684 is used.\nThe HONO_COAP_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).\nInsecure Port Only The secure port will mostly be required for production scenarios. However, it might be desirable to expose a non-DTLS secured port instead, e.g. for testing purposes. In any case, the non-secure port needs to be explicitly enabled by\nexplicitly setting HONO_COAP_AUTHENTICATIONREQUIRED to false and either explicitly setting HONO_COAP_INSECUREPORT to a valid port number or implicitly configuring the default insecure CoAP port (5683) by setting HONO_COAP_INSECUREPORTENABLED to true. The protocol adapter issues a warning on the console if HONO_COAP_INSECUREPORT is set to the default secure CoAP port (5684).\nThe HONO_COAP_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-DTLS 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.\nSetting 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).\nTip The insecure port will only be bound if the HONO_COAP_AUTHENTICATIONREQUIRED variable is set to false because the CoAP adapter authenticates clients (devices) as part of the DTLS handshake. Thus, requiring devices to authenticate effectively rules out setting up a non-DTLS secured port.\nDual 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.\nEphemeral 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.\nAuthentication The CoAP protocol is UDP based and as such uses the DTLS protocol to secure the communication between a client (device) and a server (adapter). The CoAP adapter also uses the DTLS handshake to prove its identity to devices and to authenticate the devices themselves. The DTLS protocol allows for different cipher suites to be used for doing so. These suites mainly differ from each other in the type of secret being used for proving the participants’ identity to each other.\nOne class of suites is based on a secret that is shared between the client and the server, very much like in a username/password based authentication scheme. This class of suites is called pre-shared key or PSK-based and is very popular for use cases where the devices are very constrained regarding CPU and memory. Another class of cipher suites is based on certificates which use asymmetric encryption for proving possession of the secret (the private key).\nThe CoAP adapter supports cipher suites from both classes but only supports cipher suites from the latter class which use ECDSA algorithm for authentication. In particular, this means that the client and/or server need to use elliptic curve cryptography (ECC) based keys instead of RSA based ones.\nWhen enabling the secure port without configuring an ECC based key and certificate, the adapter will only use PSK based cipher suites for authentication. When configuring an ECC based key and certificate, the adapter will also offer certificate based cipher suites to the client to use for authentication.\nIn any case the device’s credentials need to be registered with the device registry. Please refer to the Standard Credential Types and the Device Registry Management API for additional information.\n",
    "description": "",
    "tags": null,
    "title": "CoAP Adapter Configuration",
    "uri": "/hono/docs/2.7/admin-guide/coap-adapter-config/"
  },
  {
    "content": "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.\nAll 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.\nConnection 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.\nThe 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.\nOS Environment Variable\nJava System Property Mandatory Default Value Description ${PREFIX}_AMQPHOSTNAME\n${prefix}.amqpHostname no - The name to use as the hostname in the client’s AMQP open frame during connection establishment. This variable can be used to indicate the virtual host to connect to on the server. ${PREFIX}_CERTPATH\n${prefix}.certPath no - The absolute path to the PEM file containing the certificate that the client should use for authenticating to the server. This variable must be used in conjunction with ${PREFIX}_KEYPATH.\nAlternatively, the ${PREFIX}_KEYSTOREPATH variable can be used to configure a key store containing both the key as well as the certificate. ${PREFIX}_CONNECTTIMEOUT\n${prefix}.connectTimeout no 5000 The maximum amount of time (milliseconds) that the client should wait for the AMQP connection to be opened. This includes the time for TCP/TLS connection establishment, SASL handshake and exchange of the AMQP open frame. This property can be used to tune the time period to wait according to the network latency involved with the connection between the client and the service. ${PREFIX}_CREDENTIALSPATH\n${prefix}.credentialsPath no - The absolute path to a properties file that contains a username and a password property to use for authenticating to the service.\nThis variable is an alternative to using ${PREFIX}_USERNAME and ${PREFIX}_PASSWORD which has the advantage of not needing to expose the secret (password) in the client process’ environment. ${PREFIX}_FLOWLATENCY\n${prefix}.flowLatency no 20 The maximum amount of time (milliseconds) that the client should wait for credits after a link to the service has been established. ${PREFIX}_HOST\n${prefix}.host no localhost The IP address or name of the host to connect to. NB This needs to be set to an address that can be resolved within the network the client runs on. When running as a Docker container, use Docker’s --network command line option to attach the local container to the Docker network that the service is running on. ${PREFIX}_HOSTNAMEVERIFICATIONREQUIRED\n${prefix}.hostnameVerificationRequired no true A flag indicating whether the value of the ${PREFIX}_HOST variable must match the distinguished name or any of the alternative names asserted by the server’s certificate when connecting using TLS. ${PREFIX}_IDLETIMEOUT\n${prefix}.idleTimeout no 16000 Sets the amount of time in milliseconds after which a connection will be closed when no frames have been received from the remote peer. This property is also used to configure a heartbeat mechanism, checking that the connection is still alive. The corresponding heartbeat interval will be set to idleTimeout/2 ms. ${PREFIX}_INITIALCREDITS\n${prefix}.initialCredits no 200 The number of credits that a consuming client will initially issue to the service (sender) after link creation. This value effectively limits the number of messages that can be in flight unsettled. ${PREFIX}_KEYPATH\n${prefix}.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the client should use for authenticating to the server. Note that the private key is not protected by a password. You should therefore make sure that the key file can only be read by the user that the client process is running under. This variable must be used in conjunction with ${PREFIX}_CERTPATH. Alternatively, the ${PREFIX}_KEYSTOREPATH variable can be used to configure a key store containing both the key as well as the certificate. ${PREFIX}_KEYSTOREPASSWORD\n${prefix}.keyStorePassword no - The password required to read the contents of the key store. If the value starts with file: then the string after the prefix is interpreted as the path to a file to read the password from. ${PREFIX}_KEYSTOREPATH\n${prefix}.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the client should use for authenticating to the server. Either this variable or the ${PREFIX}_KEYPATH and ${PREFIX}_CERTPATH variables need to be set in order to enable SASL External based authentication to the server. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. ${PREFIX}_LINKESTABLISMENTTIMEOUT\n${prefix}.linkEstablishmentTimeout no 1000 The maximum amount of time (milliseconds) that the client should wait for the service’s attach frame during link establishment. This property can be used to tune the time period to wait according to the network latency involved with the communication link between the client and the service. ${PREFIX}_MAXFRAMESIZE\n${prefix}.maxFrameSize no -1 The maximum size (in bytes) of a single AMQP frame that the client should accept from the peer. When a peer sends a bigger frame, the connection will be closed. The default value of -1 indicates that no limit is to be imposed. ${PREFIX}_MAXMESSAGESIZE\n${prefix}.maxMessageSize no -1 The maximum size of messages (in bytes) that the client should accept from a peer. The default value of -1 indicates that messages of any size should be accepted. ${PREFIX}_MINMESSAGESIZE\n${prefix}.minMessageSize no 0 The minimum max-message-size (in bytes) that the client requires a peer to accept. The default value of 0 indicates that no minimum size is required. Sender link establishment will fail, if the max-message-size conveyed by the peer in its attach frame is smaller than this property’s value. ${PREFIX}_MAXSESSIONFRAMES\n${prefix}.maxSessionFrames no -1 The maximum number of AMQP transfer frames for sessions created on this connection. This is the number of transfer frames that may simultaneously be in flight for all links in the session. The default value of -1 indicates that no limit is to be imposed. ${PREFIX}_NAME\n${prefix}.name no - The name to use as the container-id in the client’s AMQP open frame during connection establishment. ${PREFIX}_PASSWORD\n${prefix}.password no - The password to use for authenticating to the service. ${PREFIX}_PORT\n${prefix}.port no 5671 The port that the service is listening on. ${PREFIX}_SENDMESSAGETIMEOUT\n${prefix}.sendMessageTimeout no 1000 The maximum number of milliseconds to wait for a delivery update after an event or command message was sent before the send operation is failed. Setting this value to a higher value increases the chance of successful service invocation in situations where network latency is high. ${PREFIX}_RECONNECTATTEMPTS\n${prefix}.reconnectAttempts no -1 The number of attempts (in addition to the original connection attempt) that the client should make in order to establish an AMQP connection with the peer before giving up. The default value of this property is -1 which means that the client will try forever. ${PREFIX}_RECONNECTDELAYINCREMENT\n${prefix}.reconnectDelayIncrement no 100 The factor (milliseconds) used in the exponential backoff algorithm for determining the delay before trying to re-establish an AMQP connection with the peer. The delay after an initial, failed connection attempt will be the value of the ${PREFIX}_RECONNECTMINDELAY variable. Each subsequent connection attempt will use a random delay between the minimum delay and the value determined by exponentially increasing the delay by the ${PREFIX}_RECONNECTDELAYINCREMENT factor. The overall limit of the delay time is defined by the ${PREFIX}_RECONNECTMAXDELAY variable. ${PREFIX}_RECONNECTMAXDELAY\n${prefix}.reconnectMaxDelay no 7000 The maximum number of milliseconds to wait before trying to re-establish an AMQP connection with the peer. ${PREFIX}_RECONNECTMINDELAY\n${prefix}.reconnectMinDelay no 0 The minimum number of milliseconds to wait before trying to re-establish an AMQP connection with the peer. ${PREFIX}_REQUESTTIMEOUT\n${prefix}.requestTimeout no 200 The maximum number of milliseconds to wait for a response before a service invocation is failed. Setting this value to a higher value increases the chance of successful service invocation in situations where network latency is high. ${PREFIX}_SECUREPROTOCOLS\n${prefix}.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. ${PREFIX}_SUPPORTEDCIPHERSUITES\n${prefix}.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that the client may negotiate in TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. ${PREFIX}_TLSENABLED\n${prefix}.tlsEnabled no false If set to true the connection to the peer will be encrypted using TLS and the peer’s identity will be verified using the JVM’s configured standard trust store.\nThis variable only needs to be set to enable TLS explicitly if no specific trust store is configured using the ${PREFIX}_TRUSTSTOREPATH variable. ${PREFIX}_TRUSTSTOREPATH\n${prefix}.trustStorePath no - The absolute path to the Java key store containing the CA certificates the client uses for authenticating to the service. This property must be set if the service has been configured to support TLS. The key store format can be either JKS, PKCS12 or PEM indicated by a .jks, .p12 or .pem file suffix respectively. ${PREFIX}_TRUSTSTOREPASSWORD\n${prefix}.trustStorePassword no - The password required to read the contents of the trust store. If the value starts with file: then the string after the prefix is interpreted as the path to a file to read the password from. ${PREFIX}_USELEGACYTRACECONTEXTFORMAT\n${prefix}.useLegacyTraceContextFormat no true This flag determines where OpenTelemetry trace context information will be stored in an AMQP 1.0 message sent via the client. If set to true, the legacy format will be used, writing trace context information as traceparent and tracestate properties in an x-opt-trace-context map in the message-annotations of the message. When set to false, the tracing properties will be written to the application properties of the message instead. The latter is a more generic approach, adhering to the Trace Context: AMQP protocol specification draft and being compatible with Eclipse Ditto, for example. It will be the default in Hono 3.0. ${PREFIX}_USERNAME\n${prefix}.username no - The username to use for authenticating to the service. This property (and the corresponding password) needs to be set in order to enable SASL Plain based authentication to the service. 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.\nThe 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.\nInstances 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:\nIf the response contains a no-cache directive, the response is not cached at all. 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. 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.\nOS Environment Variable\nJava System Property Mandatory Default Value Description ${PREFIX}_RESPONSECACHEMINSIZE\n${prefix}.responseCacheMinSize no 20 The minimum number of responses that can be cached. ${PREFIX}_RESPONSECACHEMAXSIZE\n${prefix}.responseCacheMaxSize no 1000 The maximum number of responses that can be cached. It is up to the particular cache implementation, how to deal with new cache entries once this limit has been reached. ${PREFIX}_RESPONSECACHEDEFAULTTIMEOUT\n${prefix}.responseCacheDefaultTimeout no 600 The default number of seconds after which cached responses should be considered invalid. The value of this property serves as an upper boundary to the value conveyed in a max-age cache directive and is capped at 86400, which corresponds to 24 hours. Using TLS The factory can be configured to use TLS for\nauthenticating 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.\nThe 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.\nThe 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.\nAddress 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.\nTo 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.\nOS Environment Variable\nJava System Property Mandatory Default Value Description ${PREFIX}_ADDRESSREWRITERULE\n${prefix}.addressRewriteRule no - The address rewrite rule in the \"$PATTERN $REPLACEMENT\" format. 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.\nFor 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.\n",
    "description": "",
    "tags": null,
    "title": "Hono Client Configuration",
    "uri": "/hono/docs/2.7/admin-guide/hono-client-configuration/"
  },
  {
    "content": "Several Hono components can be configured to support Kafka as the messaging infrastructure. The Kafka client used for this purpose can be configured by means of operating system environment variables and/or Java system properties.\nA Hono component can use multiple Kafka clients for different tasks. Each client has a type (producer, consumer, or admin client) and a name which is part of the prefix of the configuration properties used to configure the client. The name is part of the prefix of the configuration properties used to configure a client. For the clients and their names, please refer to the admin guide of the respective component.\nThe configuration properties are directly passed to the Kafka clients (without the prefixes) without Hono parsing or validating them.\nProducer Configuration Properties The org.eclipse.hono.client.kafka.CachingKafkaProducerFactory factory can be used to create Kafka producers for Hono’s Kafka based APIs. The producers created by the factory are configured with instances of the class org.eclipse.hono.client.kafka.producer.MessagingKafkaProducerConfigProperties which can be used to programmatically configure a producer.\nThe configuration needs to be provided in the form HONO_KAFKA_${CLIENTNAME}_PRODUCERCONFIG_${PROPERTY} as an environment variable or as a Java system property in the form hono.kafka.${clientName}.producerConfig.${property}, where ${PROPERTY} respectively ${property} is any of the Kafka client’s producer properties and ${CLIENTNAME} respectively ${clientName} is the name of the client to be configured, as documented in the component’s admin guide.\nThe following default properties are used, differing from the Kafka client defaults:\nProperty Name Value delivery.timeout.ms 2500 request.timeout.ms 750 max.block.ms 500 The following properties can not be set because org.eclipse.hono.client.kafka.producer.MessagingKafkaProducerConfigProperties uses fixed values instead in order to implement the message delivery semantics defined by Hono’s Telemetry and Event APIs.\nProperty Name Fixed Value key.serializer org.apache.kafka.common.serialization.StringSerializer value.serializer io.vertx.kafka.client.serialization.BufferSerializer enable.idempotence true Kafka clients used in Hono will get a unique client identifier, containing client name and component identifier. If the property client.id is provided, its value will be used as prefix for the created client identifier.\nConsumer Configuration Properties Consumers for Hono’s Kafka based APIs are configured with instances of the class org.eclipse.hono.client.kafka.consumer.MessagingKafkaConsumerConfigProperties which can be used to programmatically configure a consumer.\nThe configuration needs to be provided in the form HONO_KAFKA_${CLIENTNAME}_CONSUMERCONFIG_${PROPERTY} as an environment variable or as a Java system property in the form hono.kafka.${clientName}.consumerConfig.${property}, where ${PROPERTY} respectively ${property} is any of the Kafka client’s consumer properties and ${CLIENTNAME} respectively ${clientName} is the name of the client to be configured, as documented in the component’s admin guide.\nThe following properties can not be set because org.eclipse.hono.client.kafka.consumer.MessagingKafkaConsumerConfigProperties uses fixed values instead.\nProperty Name Fixed Value key.deserializer org.apache.kafka.common.serialization.StringDeserializer value.deserializer io.vertx.kafka.client.serialization.BufferDeserializer Kafka clients used in Hono will get a unique client identifier, containing client name and component identifier. If the property client.id is provided, its value will be used as prefix for the created client identifier.\nApart from the standard Kafka client consumer properties, this additional property may be set:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_KAFKA_${CLIENTNAME}_POLLTIMEOUT\nhono.kafka.${clientName}.pollTimeout no 250 The maximum number of milliseconds to wait for records on each consumer poll operation. Setting the timeout to a lower value will make the client more responsive, for example concerning consumer-group membership changes, in times when no messages are available for the consumer to poll. At the same time, the client will poll more frequently and thus will potentially create a higher load on the Kafka Broker. Admin Client Configuration Properties Admin clients for Hono’s Kafka based APIs are configured with instances of the class org.eclipse.hono.client.kafka.KafkaAdminClientConfigProperties which can be used to programmatically configure an admin client.\nThe configuration needs to be provided in the form HONO_KAFKA_${CLIENTNAME}_ADMINCLIENTCONFIG_${PROPERTY} as an environment variable or as a Java system property in the form hono.kafka.${clientName}.adminClientConfig.${property}, where ${PROPERTY} respectively ${property} is any of the Kafka client’s admin client properties and ${CLIENTNAME} respectively ${clientName} is the name of the client to be configured, as documented in the component’s admin guide.\nKafka clients used in Hono will get a unique client identifier, containing client name and component identifier. If the property client.id is provided, its value will be used as prefix for the created client identifier.\nCommon Configuration Properties Usually, all Kafka clients will connect to the same Kafka cluster and need the same configuration properties to establish the connection, like bootstrap.servers and the properties related to authentication and TLS configuration. Such configuration properties that are common to all the clients of a Hono component can be put in a common configuration section. This will avoid having to define duplicate configuration properties for the different client types.\nThe properties must be prefixed with HONO_KAFKA_COMMONCLIENTCONFIG_ and hono.kafka.commonClientConfig. respectively.\nA property with the same name defined in the configuration of one of the specific client types above will have precedence over the common property.\nTip The Kafka clients require at least the bootstrap.servers property to be set. This is the minimal configuration required to enable Kafka based messaging.\nTip The Kafka client configuration is composed of a number of properties that have an ambiguous mapping to environment variable names. For example, the property key \"bootstrap.servers\" in the hono.kafka.commonClientConfig map would have the same mapping to an environment variable as \"bootstrap-servers\" and \"bootstrap_servers\" (they would all map to __BOOTSTRAP_SERVERS__).\nTo resolve this ambiguity and allow ambiguous properties to be overridden using environment variables, the configuration framework relies on the correct property being defined in a configuration source which uses unambiguous property key representations and has a lower precedence than the environment variable configuration source. It’s therefore necessary to provide any such configuration property in the application.yml file or as a Java system property to help the configuration system disambiguate the property key, even if only providing a placeholder value.\nTip Some of the Kafka configuration options beneath hono.kafka.commonClientConfig need to be quoted as the keys themselves can contain hierarchical delimiters such as a period (.). An example of that is bootstrap.servers which is a single key within the hono.kafka.commonClientConfig configuration map. To represent such a key with an environment variable, you must use double underscores for representing the quoted key. For example, the environment variable to represent hono.kafka.commonClientConfig.\"bootstrap.servers\" is HONO_KAFKA_COMMONCLIENTCONFIG__BOOTSTRAP_SERVERS__.\nUsing TLS The factory can be configured to use TLS for authenticating the brokers in the Kafka cluster during connection establishment and optionally for authenticating to the broker using a client certificate. To use this, a Kafka client configuration as described in Kafka documentation - section “Security” needs to be provided, either in the common configuration or individually per client as shown above.\nKafka client metrics configuration Protocol adapters, the Command Router component and the device registry components by default report a set of metrics concerning the Kafka clients used for sending and receiving messages.\nThe metrics support can be configured using the following environment variables or corresponding system properties:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_KAFKA_METRICS_ENABLED\nhono.kafka.metrics.enabled no true If set to false, no Kafka client metrics will be reported. HONO_KAFKA_METRICS_USEDEFAULTMETRICS\nhono.kafka.metrics.useDefaultMetrics no true If set to true, a set of Kafka consumer and producer related default metrics will be reported. Additional metrics can be added via the HONO_KAFKA_METRICS_METRICSPREFIXES property described below. HONO_KAFKA_METRICS_METRICSPREFIXES\nhono.kafka.metrics.metricsPrefixes no - A comma separated list of prefixes of the metrics to be reported for the Kafka clients (in addition to the default metrics if these are used). The complete list of metrics can be viewed in the Kafka documentation. The metric names to be used here have the form kafka.[metric group].[metric name]. The metric group can be obtained from the type value in the MBean name, omitting the -metrics suffix. E.g. for an MBean name containing kafka.consumer:type=consumer-fetch-manager-metrics, the group is consumer.fetch.manager (all dashes are to be replaced by dots in metric group and name). An example of a corresponding metric name would be kafka.consumer.fetch.manager.bytes.consumed.total To include all metrics, the property value can be set to the kafka prefix. Kafka Client Version Hono components include a recent version of the Kafka client as defined by the Quarkus framework. In general, the included client should work with recent versions of Kafka brokers. However, no cross version testing is being done as part of the Hono build process. If you experience any issues using Hono with an older Kafka version, please try to connect it to a recent Kafka cluster instead before raising an issue.\n",
    "description": "",
    "tags": null,
    "title": "Hono Kafka Client Configuration",
    "uri": "/hono/docs/2.7/admin-guide/hono-kafka-client-configuration/"
  },
  {
    "content": "The Qpid Dispatch Router, together with the Apache Artemis message broker, serves as the default AMQP 1.0 Messaging Network that is used in Hono’s example deployment as described in the Deployment Guides.\nThe Dispatch Router component exposes service endpoints implementing the north bound part of Hono’s Telemetry, Event and Command \u0026 Control APIs which are used by applications to interact with devices.\nConfiguring Tenants to use AMQP 1.0 based Messaging Hono’s components by default support using Kafka based messaging infrastructure to transmit messages hence and forth between devices and applications. Hono also supports using AMQP 1.0 as the messaging infrastructure either as a replacement for or as an alternative in addition to the Kafka based infrastructure.\nIn most cases Hono’s components will be configured to use either AMQP 1.0 or Kafka based messaging infrastructure. However, in cases where both types of infrastructure are being used, Hono’s components need to be able to determine, which infrastructure should be used for messages of a given tenant. For this purpose, the configuration properties registered for a tenant support the ext/messaging-type property which can have a value of either amqp or kafka.\nThe following example shows a tenant that is configured to use the AMQP 1.0 messaging infrastructure:\n{ \"tenant-id\": \"TEST_TENANT\", \"enabled\": true, \"ext\": { \"messaging-type\": \"amqp\" } } If not explicitly set, the ext/messaging-type property’s value is kafka which indicates that Kafka is to be used for the tenant.\nInfo If an adapter is configured to connect to only one type of messaging infrastructure, the tenant specific messaging type configuration is ignored.\nDispatch Router Configuration The Dispatch Router is part of the Apache Qpid project. Hono uses the Dispatch Router by means of the EnMasse project’s Dispatch Router Docker image created from the Qpid project source code.\nThe Dispatch Router can be configured by means of configuration files. The Eclipse IoT Packages project hosts an example configuration. Please refer to the Dispatch Router documentation for details regarding the configuration file format and options.\nArtemis Broker Configuration The Artemis Broker is part of the Apache ActiveMQ project. Hono uses Artemis by means of the EnMasse project’s Artemis Docker image created from the Artemis project source code.\nThe Artemis Broker can be configured by means of configuration files. The Eclipse IoT Packages project hosts an example configuration. Please refer to the Artemis documentation for details regarding the configuration file format and options.\n",
    "description": "",
    "tags": null,
    "title": "AMQP 1.0 Messaging Network Configuration",
    "uri": "/hono/docs/2.7/admin-guide/amqp-network-config/"
  },
  {
    "content": "Hono may use an Apache Kafka cluster as messaging infrastructure.\nIn order to configure the Hono components for using a Kafka cluster, see the protocol adapter, command router and device registry admin guides.\nKafka Broker Configuration Hono requires the following broker configuration properties to be set:\nBroker config property Mandatory Description delete.topic.enable true Enables deletion of topics. This is needed for the automatic deletion of hono.command_internal.[adapterInstanceId] topics after the corresponding protocol adapter instance was stopped. Used Topics For Telemetry, Event and Command \u0026 Control Messages The Hono components publish messages to the following, tenant-specific Kafka topics, from which downstream applications will consume the messages:\nTopic name Description hono.telemetry.[tenantId] Topic for telemetry messages. hono.event.[tenantId] Topic for event messages. hono.command_response.[tenantId] Topic for command response messages. For command \u0026 control messages published by downstream applications and consumed by the Hono command router, the following topic is used:\nTopic name Description hono.command.[tenantId] Topic for command \u0026 control messages. The above topics may be created in advance with appropriate replication factor and partition count settings. Otherwise, the auto.create.topics.enable broker configuration property needs to be set to true to enable auto-creation of these topics.\nFor Hono internal messages For messages published and consumed only by Hono components, the following topics are used:\nTopic name Description hono.command_internal.[adapterInstanceId] Topic used for routing of command \u0026 control messages between Hono components. hono.notification.registry-tenant Topic used for notification messages between Hono components about changes to tenant registration data. hono.notification.registry-device Topic used for notification messages between Hono components about changes to device registration data. The hono.command_internal.[adapterInstanceId] topic name contains a unique identifier as suffix, created dynamically on protocol adapter start. Therefore this topic cannot be created in advance. It has to be made sure that the Kafka admin clients in the protocol adapters are able to create this kind of topic.\nThe hono.notification.[suffix] topics either need to be created in advance, or the auto.create.topics.enable broker configuration property needs to be set to true to enable auto-creation of these topics.\n",
    "description": "",
    "tags": null,
    "title": "Kafka Configuration",
    "uri": "/hono/docs/2.7/admin-guide/kafka-config/"
  },
  {
    "content": "Hono can be configured to support Google Pub/Sub as the messaging infrastructure. The Pub/Sub client used for this purpose can be configured by means of operating system environment variables.\nSupporting Google Pub/Sub, Hono must run on Google Kubernetes Engine to authenticate to the Google Pub/Sub API. To authenticate to the Google Pub/Sub API, Workload Identity is used and has to be configured as described in the Google Cloud Documentation.\nWarning Support for Google Pub/Sub based messaging infrastructure is considered experimental and may change without further notice.\nPublisher and Subscriber Configuration The org.eclipse.hono.client.pubsub.publisher.CachingPubSubPublisherFactory factory can be used to create Pub/Sub publishers for Hono’s Pub/Sub based APIs. The org.eclipse.hono.client.pubsub.subscriber.CachingPubSubSubscriberFactory factory can be used to create Pub/Sub subscribers for Hono’s Pub/Sub based APIs.\nPlease refer to the Quarkus Google Cloud Services extension documentation for details regarding configuration of the Pub/Sub client.\nConfiguring Tenants to use Pub/Sub based Messaging Hono’s components by default support using Kafka based messaging infrastructure to transmit messages hence and forth between devices and applications. Hono also supports using Pub/Sub as the messaging infrastructure either as a replacement for or as an alternative in addition to the Kafka based infrastructure.\nIn most cases Hono’s components will be configured to use either Pub/Sub, AMQP 1.0 or Kafka based messaging infrastructure. However, in cases where more than one type of infrastructure is being used, Hono’s components need to be able to determine, which infrastructure should be used for messages of a given tenant. For this purpose, the configuration properties registered for a tenant support the ext/messaging-type property which can have a value of either pubsub, amqp or kafka.\nThe following example shows a tenant that is configured to use the Pub/Sub based messaging infrastructure:\n{ \"tenant-id\": \"TEST_TENANT\", \"enabled\": true, \"ext\": { \"messaging-type\": \"pubsub\" } } If not explicitly set, the ext/messaging-type property’s value is kafka which indicates that Kafka is to be used for the tenant.\nInfo If an adapter is configured to connect to only one type of messaging infrastructure, the tenant specific messaging type configuration is ignored.\nUsed Topics and Subscriptions For Telemetry, Event and Command \u0026 Control Messages The Hono components publish messages to the following, tenant-specific Pub/Sub topics, from which downstream applications can create subscriptions and consume the messages:\nTopic name Description projects/${google_project_id}/topics/${tenant_id}.telemetry Topic for telemetry messages. projects/${google_project_id}/topics/${tenant_id}.event Topic for event messages. projects/${google_project_id}/topics/${tenant_id}.command_response Topic for command response messages. For command \u0026 control messages published by downstream applications, the following topic is used:\nTopic name Description projects/${google_project_id}/topics/${tenant_id}.command Topic for command \u0026 control messages. For command \u0026 control messages consumed by the Hono command router, the following subscription is used:\nSubscription name Description projects/${google_project_id}/subscriptions/${tenant_id}.command Subscription for command \u0026 control messages. The above topics and subscriptions must be created in advance.\nFor Hono internal messages For messages published only by Hono components, the following topics are used:\nTopic name Description projects/${google_project_id}/topics/${adapter_instance_id}.command_internal Topic used for routing of command \u0026 control messages between Hono components. projects/${google_project_id}/topics/registry-tenant.notification Topic used for notification messages between Hono components about changes to tenant registration data. projects/${google_project_id}/topics/registry-device.notification Topic used for notification messages between Hono components about changes to device registration data. For messages consumed only by Hono components, the following subscriptions are used:\nSubscription name Description projects/${google_project_id}/subscriptions/${adapter_instance_id}.command_internal Subscription used for routing of command \u0026 control messages between Hono components. projects/${google_project_id}/subscriptions/registry-tenant.notification Subscription used for notification messages between Hono components about changes to tenant registration data. projects/${google_project_id}/subscriptions/registry-device.notification Subscription used for notification messages between Hono components about changes to device registration data. The projects/${google_project_id}/topics/${adapter_instance_id}.command_internal topic and the projects/${google_project_id}/subscriptions/${adapter_instance_id}.command_internal subscription name contains a unique identifier as prefix, created dynamically on protocol adapter start. Therefore, this topic cannot be created in advance. It is created by a Pub/Sub based admin client in the protocol adapters.\nThe projects/${google_project_id}/topics/${PREFIX}.notification topics and subscriptions need to be created in advance.\n",
    "description": "",
    "tags": null,
    "title": "Google Pub/Sub Messaging Configuration",
    "uri": "/hono/docs/2.7/admin-guide/pubsub-config/"
  },
  {
    "content": "The individual components of an Eclipse Hono™ installation, e.g. the protocol adapters, messaging infrastructure, Hono Auth etc. and the clients attaching to Hono in order to send and receive data all communicate with each other over IP based networking infrastructure. The Hono components and the clients will usually not be located on the same local network but will probably communicate over public networking infrastructure. For most use cases it is therefore desirable, if not necessary, to provide for confidentiality of the data being transferred between these components.\nThis section describes how Hono supports confidentiality by means of Transport Layer Security (TLS) and how to configure it.\nEnabling TLS All of Hono’s components can be configured to use TLS for establishing an encrypted communication channel with peers. When a client initiates a connection with a server, the TLS handshake protocol is used to negotiate parameters of a secure channel to be used for exchanging data. The most important of those parameters is a secret (symmetric) encryption key that is only known to the client and the server and which is used to transparently encrypt all data being sent over the connection as long as the connection exists. With each new connection, a new secret key is negotiated.\nUsing TLS in this way requires configuring the server component with a cryptographic private/public key pair and a certificate which binds an identity claim to the public key. It is out of scope of this document to describe the full process of creating such a key pair and acquiring a corresponding certificate. The demo-certs module already contains a set of keys and certificates to be used for evaluation and demonstration purposes. Throughout the rest of this section we will use these keys and certificates. Please refer to the demo-certs/README.md file for details regarding how to create your own keys and certificates.\nThe following sections provide information regarding the configuration of TLS for Hono’s components.\nAuth Server The Auth Server supports the use of TLS for incoming connections to its Authentication API endpoint. Please refer to the Auth Server admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder includes the following demo keys and certificates to be used with the Auth Server for that purpose.\nFile Description auth-server-key.pem The example private key for creating signatures. auth-server-cert.pem The example certificate asserting the server’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. Kafka Broker Please refer to the Apache Kafka documentation for details regarding the configuration of TLS.\nThe demo-certs/certs folder includes the following demo keys and certificates to be used with the Kafka broker for that purpose:\nFile Description trusted-certs.pem Trusted CA certificates to use for verifying signatures. Dispatch Router Please refer to the Dispatch Router documentation for details regarding the configuration of TLS.\nThe demo-certs/certs folder includes the following demo keys and certificates to be used with the Dispatch Router for that purpose:\nFile Description qdrouter-key.pem The example private key for creating signatures. qdrouter-cert.pem The example certificate asserting the server’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. Command Router The Command Router supports the use of TLS for incoming connections to its Command Router API endpoint. It also supports using TLS for outgoing connections to the Authentication, Tenant and Device Registration service endpoints, the messaging infrastructure and the data grid used for storing routing information.\nPlease refer to the Command Router admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the file based Device Registry for that purpose.\nFile Description auth-server-cert.pem The certificate of the Auth Server, used to verify the signatures of tokens issued by the Auth Server. command-router-key.pem The example private key for creating signatures. command-router-cert.pem The example certificate asserting the server’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. JDBC Based Device Registry The JDBC based Device Registry supports the use of TLS for incoming connections to its Tenant, Device Registration, Credentials and Device Registry Management API endpoints. It also supports using TLS for outgoing connections to the Authentication service endpoint and the database server.\nPlease refer to the JDBC based Device Registry admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the file based Device Registry for that purpose.\nFile Description auth-server-cert.pem The certificate of the Auth Server, used to verify the signatures of tokens issued by the Auth Server. device-registry-key.pem The example private key for creating signatures. device-registry-cert.pem The example certificate asserting the server’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. MongoDB Based Device Registry The MongoDB based Device Registry supports the use of TLS for incoming connections to its Tenant, Device Registration, Credentials and Device Registry Management API endpoints. It also supports using TLS for outgoing connections to the Authentication service endpoint and the Mongo database server.\nPlease refer to the MongoDB based Device Registry admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the MongoDB based Device Registry for that purpose.\nFile Description auth-server-cert.pem The certificate of the Auth Server, used to verify the signatures of tokens issued by the Auth Server. device-registry-key.pem The example private key for creating signatures. device-registry-cert.pem The example certificate asserting the server’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. AMQP Adapter The adapter supports the use of TLS for incoming connections from devices. It also supports the use of TLS for outgoing connections to the Tenant, Device Registration, Credentials and Command Router service endpoints and the messaging infrastructure.\nFor this purpose, the adapter can be configured with a server certificate and private key. Please refer to the AMQP adapter admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the adapter for that purpose.\nFile Description amqp-adapter-key.pem The example private key for creating signatures. amqp-adapter-cert.pem The example certificate asserting the adapter’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. CoAP Adapter The adapter supports the use of Datagram TLS (DTLS) for incoming connections from devices. It also supports the use of TLS for outgoing connections to the Tenant, Device Registration, Credentials and Command Router service endpoints and the messaging infrastructure.\nFor this purpose, the adapter can be configured with a server certificate and private key. Please refer to the CoAP adapter admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the adapter for that purpose.\nFile Description coap-adapter-key.pem The example private key for creating signatures. coap-adapter-cert.pem The example certificate asserting the adapter’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. HTTP Adapter The adapter supports the use of TLS for incoming connections from devices. It also supports the use of TLS for outgoing connections to the Tenant, Device Registration, Credentials and Command Router service endpoints and the messaging infrastructure.\nFor this purpose, the adapter can be configured with a server certificate and private key. Please refer to the HTTP adapter admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the adapter for that purpose.\nFile Description http-adapter-key.pem The example private key for creating signatures. http-adapter-cert.pem The example certificate asserting the adapter’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. MQTT Adapter The adapter supports the use of TLS for incoming connections from devices. It also supports the use of TLS for outgoing connections to the Tenant, Device Registration, Credentials and Command Router service endpoints and the messaging infrastructure.\nFor this purpose, the adapter can be configured with a server certificate and private key. Please refer to the MQTT adapter admin guide for details regarding the required configuration steps.\nThe demo-certs/certs folder contains the following demo keys and certificates to be used with the adapter for that purpose.\nFile Description mqtt-adapter-key.pem The example private key for creating signatures. mqtt-adapter-cert.pem The example certificate asserting the adapter’s identity. trusted-certs.pem Trusted CA certificates to use for verifying signatures. Business Application When the connection between a business application and Hono’s messaging infrastructure (i.e. the Kafka broker or the Dispatch Router) is supposed to be secured by TLS (which is a good idea), then the application needs to be configured to trust the CA that signed the messaging infrastructure’s certificate.\nApplications can use Hono’s org.eclipse.hono.application.client.kafka.impl.KafkaApplicationClientImpl and/or org.eclipse.hono.application.client.amqp.ProtonBasedApplicationClient classes to interact with Hono’s messaging infrastructure. The clients need to be configured with a trust store that contains the messaging infrastructure’s CA certificate.\nPlease refer to the Hono Client Configuration Guide and Hono Kafka Client Configuration Guide for details regarding the configuration of the clients.\nThe demo-certs/certs folder contains the following demo keys to be used with client applications for that purpose.\nFile Description trusted-certs.pem Trusted CA certificates to use for verifying signatures. Using OpenSSL Hono’s individual services are implemented in Java and therefore, by default, use the SSL/TLS engine that comes with the Java Virtual Machine that the services are running on. In case of the Docker images provided by Hono this is the SSL engine of OpenJDK. While the standard SSL engine has the advantage of being a part of the JVM itself and thus being available on every operating system that the JVM is running on without further installation, it provides only limited performance and throughput when compared to native TLS implementations like OpenSSL.\nIn order to address this problem, the Netty networking library that is used in Hono’s components can be configured to employ the OpenSSL instead of the JVM’s SSL engine by means of Netty’s Forked Tomcat Native (tcnative) module.\nThe tcnative module comes in several flavors, corresponding to the way that the OpenSSL library has been linked in. The statically linked versions include a specific version of OpenSSL (or BoringSSL for that matter) and is therefore most easy to use on supported platforms, regardless of whether another version of OpenSSL is already installed or not. In contrast, the dynamically linked variants depend on a particular version of OpenSSL being already installed on the operating system. Both approaches have their pros and cons and Hono therefore does not include tcnative in its Docker images by default, i.e. Hono’s services will use the JVM’s default SSL engine by default.\nConfiguring Containers When starting up any of Hono’s Docker images as a container, the JVM will look for additional jar files to include in its classpath in the container’s /opt/hono/extensions folder. Thus, using a specific variant of tcnative is just a matter of configuring the container to mount a volume or binding a host folder at that location and putting the desired variant of tcnative into the corresponding volume or host folder.r Assuming that the Auth Server should be run with the statically linked, BoringSSL based tcnative variant, the following steps are necessary:\nDownload tcnative matching the platform architecture (linux-x86_64). Put the jar file to a folder on the Docker host, e.g. /tmp/tcnative. Start the Auth Server Docker image mounting the host folder: docker run --name hono-auth-server --mount type=bind,src=/tmp/tcnative,dst=/opt/hono/extensions,ro ... eclipsehono/hono-service-auth Note that the command given above does not contain the environment variables and secrets that are usually required to configure the service properly.\nWhen the Auth Server starts up, it will look for a working variant of tcnative on its classpath and (if found) use it for establishing TLS connections. The service’s log file will indicate whether the JVM’s default SSL engine or OpenSSL is used.\nUsing a Docker volume instead of a bind mount works the same way but requires the use of volume as the type of the --mount parameter. Please refer to the Docker reference documentation for details.\nWarning Configuring containers to use OpenSSL the way described above does not work with container images based on native executables.\nServer Name Indication (SNI) Server Name Indication can be used to indicate to a server the host name that the client wants to connect to as part of the TLS handshake. This is useful in order to be able to host multiple virtual servers on a single network address. In particular, SNI allows server components to select a server certificate that matches the domain name indicated by the client using SNI.\nHono’s protocol adapters support virtual servers by means of SNI as described above. Devices can then connect to a protocol adapter using any one of the configured virtual domain names.\nThe following steps a re necessary in order to configure the protocol adapters with multiple virtual servers:\nCreate Server Certificate(s)\nWhen a device establishes a connection to one of Hono’s protocol adapters using one of its virtual domain names, then it includes the domain name in its TLS hello message by means of the SNI extension. The server can then use this information to determine the matching server certificate and corresponding private key that is required to perform the TLS handshake.\nIt is therefore necessary to create a private key and certificate for each virtual server to be hosted. The virtual server’s domain name needs to be added to the certificate’s Subject Alternative Name (SAN) list in order for Hono to be able to determine the key/certificate pair to use for the TLS handshake with the device. Please refer to the vert.x SNI guide for details on how this works under the hood.\nHono’s protocol adapters then need to be configured with the server certificates and keys. In order to do so, the certificates and corresponding private keys need to be added to a key store. Hono supports the JKS and PKCS12 key store formats for that purpose. Once the key store has been created, Hono’s protocol adapters need to be configured with the path to the key store by means of the adapters’ KEY_STORE_PATH configuration variable. Please refer to the protocol adapter admin guides for details on how to configure the key store path.\nEnable SNI for Hono’s Protocol Adapters\nHono’s protocol adapters can be configured to support SNI by means of the SNI configuration variable. Please refer to the protocol adapter admin guides for details on how to set this variable.\nVerify Configuration\nThe setup can be verified by means of the command line tools that are part of OpenSSL. Assuming that the MQTT protocol adapter’s IP address is 10.100.84.23, its secure endpoint is bound to port 31884 and it has been configured with a certificate using domain name my-hono.eclipse.org, then the following command can be used to test if a TLS secured connection with the adapter using that virtual host name can be established successfully:\nopenssl s_client -connect 10.100.84.23:31884 -servername my-hono.eclipse.org ",
    "description": "",
    "tags": null,
    "title": "Secure Communication",
    "uri": "/hono/docs/2.7/admin-guide/secure_communication/"
  },
  {
    "content": "The individual components of an Eclipse Hono™ installation need to work together in order to provide their functionality to devices and applications. Under normal circumstances these interactions work flawlessly. However, due to the nature of distributed systems, any one (or more) of the components may crash or become otherwise unavailable due to arbitrary reasons. This page describes how Hono supports operations teams by providing insights into the individual service components and their interactions with each other by means of reporting metrics and tracing the processing of individual messages through the system.\nWhen a device uploads telemetry data to the HTTP adapter, the adapter invokes operations on the Device Registration, Credentials and the Tenant services in order to authenticate and authorize the device before sending the telemetry data downstream to the messaging infrastructure. The overall success of this process and the latency involved before the message reaches the consumer is determined by the individual interactions between the service components.\nMonitoring In a production environment, an operations team will usually want to keep track of some key performance indicators (KPI) which allow the team to determine the overall health of the system, e.g. memory and CPU consumption etc. Hono supports the tracking of such KPIs by means of metrics it can be configured to report. The metrics are usually collected in a time series database like InfluxDB or Prometheus and then visualized on a monitoring dash-board built using frameworks like Grafana. Such a dash-board can usually also be configured to send alarms when certain thresholds are exceeded.\nMetrics usually provide insights into the past and current status of an individual component. The values can be aggregated to provide a picture of the overall system’s status. As such, metrics provide a great way to monitor system health and, in particular, to anticipate resource shortages and use such knowledge to pro-actively prevent system failure.\nEnabling Collection of Metrics The Hono build supports configuration of the Prometheus metrics back end by means of the metrics-prometheus Maven profile.\nThe profile is not active by default and needs to be activated explicitly:\nmvn clean install -Pmetrics-prometheus ... Most of the metrics back ends expect a component to actively push metrics to an endpoint provided by the back end. However, Prometheus is different in that it polls (or scrapes) all components periodically for new metrics data. For this to work, the Prometheus server needs to be configured with the host names/IP addresses of the components to monitor.\nThe components themselves need to expose a corresponding HTTP endpoint that the Prometheus server can connect to for scraping the meter data. All Hono components that report metrics can be configured to expose such an endpoint via their Health Check server which already exposes endpoints for determining the component’s readiness and liveness status.\nHealth Check Server Configuration All of Hono’s service components and protocol adapters contain a Health Check server which can be configured to expose several HTTP endpoints for determining the component’s status. Under the hood, Hono uses Quarkus’ SmallRye Health extension to implement the health check server.\nIn particular, the server exposes a /started, a /readiness, a /liveness and an optional /prometheus URI endpoint.\nThe former three endpoints are supposed to be used by container orchestration platforms like Kubernetes to monitor the runtime status of the containers that it manages. These endpoints are always exposed when the health check server is started.\nThe /prometheus endpoint can be used by a Prometheus server to retrieve collected meter data from the component. It is only exposed if Prometheus has been configured as the metrics back end as described above.\nPlease refer to the Quarkus SmallRye Health extension documentation for details regarding configuration. The table below provides an overview of the configuration properties that have a Hono specific default value that differs from the Quarkus default:\nOS Environment Variable\nJava System Property Value QUARKUS_HTTP_NON_APPLICATION_ROOT_PATH\nquarkus.http.non-application-root-path / QUARKUS_HTTP_PORT\nquarkus.http.port 8088 QUARKUS_SMALLRYE_HEALTH_LIVENESS_PATH\nquarkus.smallrye-health.liveness-path liveness QUARKUS_SMALLRYE_HEALTH_READINESS_PATH\nquarkus.smallrye-health.readiness-path readiness QUARKUS_SMALLRYE_HEALTH_ROOT_PATH\nquarkus.smallrye-health.root-path / Logging By default, all Hono components will log to the system console and can be configured using environment variables with the QUARKUS_LOG_CONSOLE_ prefix or using corresponding system properties. Logging to a file and syslog is also available. See the configuration reference for details.\nLog formatting can be configured by either setting QUARKUS_LOG_CONSOLE_FORMAT, or, to enable logging in JSON format, by setting QUARKUS_LOG_CONSOLE_JSON_ENABLED to true. Please refer to the Quarkus documentation for details.\nWarning Support for using the QUARKUS_LOG_CONSOLE_JSON environment variable for enabling JSON logging has been deprecated in the underlying Quarkus framework and support for it will be removed altogether in a future version of Hono. Please update your configuration to use the QUARKUS_LOG_CONSOLE_JSON_ENABLED variable instead.\nAdditionally, the Hono components support the sending of log messages to a centralized log management system like Graylog, Logstash or Fluentd. This is done by means of the quarkus-logging-gelf extension, using TCP or UDP to send logs in the Graylog Extended Log Format (GELF). This can also be enabled using environment variables with the QUARKUS_LOG_HANDLER_GELF_ prefix or using corresponding system properties. Please refer to Quarkus’ configuration reference for details.\nTracing In normal operation the vast majority of messages should be flowing through the system without any noteworthy delays or problems. In fact, that is the whole purpose of Hono. However, that doesn’t mean that nothing can go wrong. For example, when a tenant’s device administrator changes the credentials of a device in the Credentials service but has not yet updated the credentials on the device yet, then the device will start to fail in uploading any data to the protocol adapter it connects to. After a while, a back end application’s administrator might notice, that there hasn’t been any data being received from that particular device for quite some time. The application administrator therefore calls up the Hono operations team and complains about the data being lost somewhere.\nThe operations team will have a hard time determining what is happening, because it will need to figure out which components have been involved in the processing of the device and why the data hasn’t been processed as usual. The metrics alone usually do not help much here because metrics are usually not scoped to individual devices. The logs written by the individual components, on the other hand, might contain enough information to correlate individual entries in the log with each other and thus trace the processing of the message throughout the system. However, this is usually a very tedious (and error prone) process and the relevant information is often only logged at a level (e.g. DEBUG) that is not used in production (often INFO or above).\nIn order to address this problem, Hono’s service components are instrumented to produce tracing data via OpenTelemetry (with the instrumentation in the code using OpenTracing as described below). OpenTelemetry provides an end-to-end implementation to generate, emit, collect, process and export tracing data. The Hono container images all can be configured to send tracing data to an OpenTelemetry collector from which data can be exported to a back-end like Jaeger. The decision, whether a trace should be sampled and exported, controlling the amount of tracing data to be collected, is configured by means of a Sampler configuration.\nHono supports configuration of the trace exporter by means of the following configuration properties:\nOS Environment Variable\nJava System Property Type Default Value Description QUARKUS_OTEL_EXPORTER_OTLP_ENDPOINT\nquarkus.otel.exporter.otlp.endpoint string - The OTLP endpoint of the OpenTelemetry Collector to connect to. The endpoint must start with either http:// or https://. Please refer to the Quarkus OpenTelemetry documentation for further configuration options for the tracer exporter.\nThe sampler can be configured using the following OpenTelemetry SDK configuration properties.\nOS Environment Variable\nJava System Property Type Default Value Description OTEL_TRACES_SAMPLER\notel.traces.sampler string parentbased_always_on The sampler to use for determining if a tracing span should be reported. Please refer to the OpenTelemetry documentation for supported values.\nIn addition to the standard samplers, a rate-limiting sampler can be configured by setting this property to rate_limiting or rate-limiting and using the OTEL_TRACES_SAMPLER_ARG property to set the maximum number of traces to report per second. OTEL_TRACES_SAMPLER_ARG\notel.traces.sampler.arg string - A value to be used as the sampler argument. The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each sampler type defines its own expected input, if any. Please refer to the OpenTelemetry documentation for details. Tip The sampler being created will always be a parent based sampler. For example, configuring a sampler of type parentbased_traceidratio will yield the exact same result as configuring a sampler of type traceidratio.\nDeprecated Sampler configuration properties In previous versions of Hono, configuring the Sampler was also possible using the Quarkus specific configuration properties quarkus.opentelemetry.tracer.sampler and quarkus.opentelemetry.tracer.sampler.ratio. Usage of these properties for configuring an always on, always off or a ratio based sampler still works but is deprecated and their support will be removed completely in Hono 3.0.0. Please use the standard OpenTelemetry SDK properties instead.\nIn order to integrate traces from Hono with those from other applications, Hono supports reading and writing trace context information from and to messages exchanged with these applications. This is done according to the W3C Trace Context and the W3C Baggage specifications.\nOpenTracing instrumentation OpenTracing is a predecessor to OpenTelemetry. Hono components still use OpenTracing APIs, but use the OpenTracing shim from the OpenTelemetry SDK as OpenTracing implementation, letting traces be exported in the OpenTelemetry format.\nEnforcing the recording of traces for a tenant Typically, in production systems, the tracing components will be configured to not store all trace spans in the tracing back end, in order to reduce the performance impact. For debugging purposes it can however be beneficial to enforce the recording of certain traces. Hono allows this by providing a configuration option in the Tenant information with which all traces concerning the processing of telemetry, event and command messages for that specific tenant will be recorded. Furthermore, this enforced trace sampling can be restricted to only apply to messages sent in the context of a specific authentication identifier. Please refer to the description of the tracing object in the Tenant Information for details.\n",
    "description": "",
    "tags": null,
    "title": "Monitoring \u0026 Tracing",
    "uri": "/hono/docs/2.7/admin-guide/monitoring-tracing-config/"
  },
  {
    "content": "Developer Guide Learn how to build Eclipse Hono™ and how to integrate your custom components with it.\n",
    "description": "",
    "tags": null,
    "title": "Developer Guide",
    "uri": "/hono/docs/2.7/dev-guide/"
  },
  {
    "content": "Hono can be deployed using the pre-built Docker images available from our Docker Hub repositories. However, customizing and/or extending Hono’s functionality requires building the images from source code.\nThis page provides step by step instructions for getting the source code and building the Hono’s Docker images from it.\nPrerequisites for building Hono Docker Creating Hono’s container images using the Hono build process requires a Docker daemon running either locally or on another host you have access to. Please follow the instructions on the Docker web site to install Docker on your platform.\nIn case the docker daemon is not running locally, the following environment variable needs to be set in order for the examples in the remainder of this page to run successfully:\nexport DOCKER_HOST=tcp://${host}:${port} with ${host} and ${port} reflecting the name/IP address and port of the host where Docker is running on.\nJava Hono is written in Java and therefore requires a Java Development Kit (JDK) version 17 or newer installed on your computer. Please follow the JDK vendor’s instructions for installing Java on your operating system.\nMaven Hono’s build process is based on Apache Maven. You need Maven 3.8.1 or newer to build Hono. Please follow the installation instructions on the Maven home page.\nGit A Git client is required if you want to contribute changes/improvements to the Hono project. It is not necessary for simply building Hono locally. Please refer to the Git Downloads page for installation instructions.\nGetting the Hono Source Code Either\ndownload the latest release archive and extract the archive to a local folder or clone the Hono source code repository from GitHub: git clone https://github.com/eclipse-hono/hono.git This will create a hono folder in the current working directory and clone the whole repository into that folder. Starting the Hono Build Process Run the following from the source folder:\nexport DOCKER_HOST # in the \"hono\" folder containing the source code mvn clean install -Pbuild-docker-image,metrics-prometheus This will build all libraries, Docker images and example code.\nTip The first build might take several minutes because Docker will need to download all the base images that Hono is relying on. However, most of these will be cached by Docker so that subsequent builds will be running much faster.\nGathering Code Coverage Information for Unit Tests Hono’s unit tests can be configured to gather code coverage information during execution using the JaCoCo Maven plugin. The plugin is disabled by default and can be enabled by setting the jacoco.skip maven property to false:\n# in the \"hono\" folder containing the source code mvn clean install -Djacoco.skip=false -Pbuild-docker-image,metrics-prometheus The plugin will produce a target/jacoco.exec file in each module which contains the (binary) coverage data. It will also produce XML data files under target/site/jacoco in each module. Tools like SonarQube can be used to collect and properly format this data.\nUsing custom Image Names The container images being created will have names based on the following pattern: ${docker.registry-name}/${docker.image.org-name}/${project.artifactId}:${project.version}.\nThe variables in the name are standard Maven properties. The default value for the docker.registry-name property is index.docker.io. The default value for docker.image.org-name is eclipse. The following build command creates Hono’s images using the quay.io registry and the custom repository name:\nmvn clean install -Pbuild-docker-image,metrics-prometheus -Ddocker.registry-name=quay.io -Ddocker.image.org-name=custom Building native Images The build process supports building native Docker images using the GraalVM for some of Hono’s components. In order to do so, the build-native-image Maven profile needs to be activated:\n# in the \"hono\" folder containing the source code mvn clean install -Pbuild-native-image,metrics-prometheus Info Support for native images is an experimental feature. The build-native-image and the build-docker-image profiles are mutually exclusive. However, they can be built one after the other.\nPushing Images The container images that are created as part of the build process can be automatically pushed to a container registry using the docker-push-image Maven profile:\nmvn clean install -Pbuild-docker-image,metrics-prometheus,docker-push-image Note that the container registry might require authentication in order to push images. The build uses the Docker Maven Plugin for creating and pushing images. Please refer to the plugin documentation for details regarding how to configure credentials for the registry.\nBuilding Images for the arm64 Platform By default, the build process creates container images for the host system platform. For example when running the build on an amd64 based system, the container images created will be for the amd64 platform as well.\nImages for the arm64 platform can, of course, be created by running the build on an arm64 based system. However, it is also possible to create images for arbitrary platforms by means of Docker’s buildx command.\nOn Linux based hosts it is possible to use QEMU for building images for other platforms than the host system as described in this blog post.\nOnce QEMU and Docker buildx support have been set up, the docker-multiarch-build Maven profile can be used to build container images for both the amd64 as well as the arm64 platforms:\nmvn clean install -Pbuild-docker-image,docker-multiarch-build,docker-push-image,metrics-prometheus -Ddocker.registry-name=registry.custom.org -Ddocker.image.org-name=my-repo Note that the docker-push-image profile has been activated as well. This is necessary because buildx currently does not support loading multiple platform build results into the local image cache. Therefore, the created images need to be pushed to a container registry instead. The docker.registry-name and docker.image.org-name Maven properties can be used to set the (host) name of the container registry and the name of the image repository to use for the container image names.\nInfo While creating arm64 specific container images for Hono’s components is necessary in order to run Hono on an arm64 based platform, it may not be sufficient to do so. That is because Hono depends on several other (external) services to be available. For example, the Mongo DB based registry implementation needs to be configured with a connection to a Mongo DB server and the Command Router should be configured with access to an Infinispan data grid in a production environment. Container images for these services may or may not be available for the arm64 platform, so these services might need to be deployed to an amd64 based platform or hosted externally.\nRunning the Integration Tests The source code for Hono comes with a test suite for integration testing. To trigger these tests, change to the tests folder and execute:\n# in the \"hono/tests\" folder containing the test suite mvn verify -Prun-tests The tests are executed against the Docker images of the Hono components. Because of that, it is necessary to build the respective images as described above before the execution of the tests. See the hono/tests/readme.md file for more information regarding the test suite.\nIDE setup Checkstyle Hono uses Checkstyle to ensure its code conforms to a set of defined coding rules. Corresponding checks are done during the Hono build by means of the Maven Checkstyle plugin. In order to integrate the coding rules in the IDE, the corresponding plugin (e.g. Eclipse Checkstyle Plugin or Checkstyle-IDEA) can be configured to use the legal/src/main/resources/checkstyle/default.xml configuration file.\nThe checkstyle.suppressions.file Checkstyle configuration property should point to the legal/src/main/resources/checkstyle/suppressions.xml file.\nCode Formatter In the Eclipse IDE, the following files can be used to configure the Java code style formatter according to the style used in Hono:\neclipse/hono-code-style.xml eclipse/hono-clean-up-profile.xml eclipse/hono.importorder In Intellij IDEA, the above code style and import order configuration files can be applied by means of the Adapter for Eclipse Code Formatter IDEA plugin.\nRunning tests When running Hono unit tests in the IDE, the log output can be configured via the corresponding src/test/resources/application.yml file. Note that by default, color output is enabled via the quarkus.log.console.color property. To see the colored output in Eclipse, the ANSI Escape in Console plugin can be used. The output looks best when using a dark IDE theme.\n",
    "description": "",
    "tags": null,
    "title": "Building from Source",
    "uri": "/hono/docs/2.7/dev-guide/building_hono/"
  },
  {
    "content": "Eclipse Hono™ comes with a Java client for the AMQP adapter. It is intended for the implementation of (prototype) devices, (protocol) gateways and/or (end-to-end) tests. The client is based on Eclipse Vert.x.\nThe client is represented by the AmqpAdapterClient class in the hono-client-device-amqp module. Instances can be created using the create(HonoConnection) factory method.\nThe client provides methods for each of the following operations:\nGetting a receiver for receiving command \u0026 control messages (via the AmqpAdapterClient createCommandConsumer / createDeviceSpecificCommandConsumer methods) Sending a telemetry message (via the inherited TelemetrySender sendTelemetry method) Sending an event message (via the inherited EventSender sendEvent method) Sending a response to a previously received command (via the inherited CommandResponder sendCommandResponse method) Please refer to the javadoc of the classes for details.\nFor examples of how to use the client, see the example implementation in the AmqpExampleDevice class.\nUsage in a Gateway There are two ways to subscribe to commands for use in a gateway:\nGateway subscribing for commands for a specific device: The gateway subscribes individually for each connected device by creating a command consumer for the specific device. Gateway subscribing for commands for all its devices: The gateway subscribes for commands sent to all the different devices that the gateway acts on behalf of by creating a command consumer that is not scoped on a specific device. Subscribing for all devices does not work if multiple instances of the gateway are running at the same time, because a command is only sent to one receiver, and this may be an instance that has no connection to the device. On the other hand, subscribing for a specific device once it connects to the gateway instance (and closing the subscription once it disconnects) may not work for device-oriented protocols that are not connection-based.\n",
    "description": "",
    "tags": null,
    "title": "AMQP Adapter Client for Java",
    "uri": "/hono/docs/2.7/dev-guide/amqp_adapter_client/"
  },
  {
    "content": "Eclipse Hono™ comes with a default HTTP Adapter which can be used to interact with devices via HTTP. The default HTTP Adapter also serves as a blueprint for implementing a custom HTTP protocol adapter.\nThis section will guide you through the steps to build your own custom HTTP protocol adapter.\nPrerequisites You should be familiar with the setup and start of Hono. Refer to the Getting Started guide.\nThe standard HTTP Adapter Hono’s HTTP Adapter supports telemetry and event data processing. Please refer to the HTTP Adapter User Guide and HTTP Adapter Admin Guide for details regarding the usage and configuration of the HTTP Adapter.\nYou can find the source of the HTTP Adapter at https://github.com/eclipse-hono/hono/tree/master/adapters/http.\nAnatomy of the standard HTTP Adapter Like many other Hono components, the HTTP Adapter is built on top of the Vert.x framework.\nThe HTTP Adapter’s VertxBasedHttpProtocolAdapter class is derived from an abstract base class. This base class implements the standard functionality for component initialization, receiving HTTP requests from devices or external clients, and forwarding of data to the downstream AMQP Messaging Network.\nDerive a custom HTTP Protocol Adapter Use the standard HTTP Adapter as a blueprint.\nAdding Routes In Vert.x, a route is a mapping of an HTTP request to a handler. Inside a route, Vert.x provides a RoutingContext instance which gives access to the HTTP request (and response) object containing the HTTP headers.\nThe standard HTTP Adapter overrides the abstract method addRoutes(), provided by the base class, and adds routes for processing telemetry data and events.\n// route for uploading telemetry data router.route(HttpMethod.PUT, String.format(\"/telemetry/:%s/:%s\", PARAM_TENANT, PARAM_DEVICE_ID)) .handler(ctx -\u003e uploadTelemetryMessage(ctx, getTenantParam(ctx), getDeviceIdParam(ctx))); The route for telemetry data parses the HTTP request, extracts the tenant and deviceId parameters from the request URL path, and forwards the message payload to the method uploadTelemetryMessage(), provided by the base class.\nInfo Note the Vert.x place holder indicators : inside the URL path pattern /telemetry/:%s/:%s. Vert.x makes matching place holders available as request parameters. See Capturing path parameters in the Vert.x documentation.\nThe route for events looks very similar to the route for telemetry data. It forwards the event message payload to the uploadEventMessage() method.\nPlease refer to the Telemetry API and Event API for details about the different Hono APIs.\nIn the custom HTTP protocol adapter adapt the routes according to your needs.\nBuild and run the custom HTTP Protocol Adapter If you have Hono running, you can launch your custom HTTP protocol adapter as a Docker Container or a Quarkus application.\nYou may adopt the Maven profile build-docker-image from the Maven POM file of the standard HTTP Adapter into your custom adapter’s Maven POM file.\nFollow the guidelines for running the HTTP Adapter in HTTP Adapter. Don’t forget to configure the custom protocol adapter to bind to a different port than the standard HTTP Adapter if you intend to run them both at the same time. See the Port Configuration section of the HTTP Adapter documentation for details.\nUsing the custom HTTP Protocol Adapter Now that you have your custom HTTP protocol adapter up and running, you can use any HTTP client, like curl or HTTPie, to publish data to your custom adapter.\nNote that before publishing data to your custom HTTP protocol adapter, you need to start a consumer for the tenant you intend to publish data for. Otherwise you will not be able to successfully send data. For this purpose, you may use the example consumer as described in the Getting Started guide.\nFurther extend the custom HTTP Protocol Adapter The abstract base class includes additional hooks which you may use to plug into the adapter’s life cycle:\nHook Description preStartup() called before start of adapter’s HTTP server onStartupSuccess() called after successful start of adapter preShutdown() called before stop of adapter’s HTTP server postShutdown called after successful stop of adapter ",
    "description": "",
    "tags": null,
    "title": "Implement a Custom Hono HTTP Protocol Adapter",
    "uri": "/hono/docs/2.7/dev-guide/custom_http_adapter/"
  },
  {
    "content": "To illustrate how Eclipse Hono™ can be integrated with Java code, a simple application is provided that consumes telemetry and event data for devices belonging to the default tenant.\nIt also includes support for Command \u0026 Control:\nIf indicated by a received downstream message that contains a ttd value (refer to Device notifications for details) it tries to send a command to the device. If the value of ttd indicates that the device stays connected for an unlimited time (ttd == -1), the application will periodically repeat to send a command until notified the device is disconnected again (ttd == 0). This application shall serve as a blueprint to integrate your existing Java source code with Hono. Its code is found in the example module in the package org.eclipse.hono.vertx.example.\nThe provided classes are kept as simple as possible (in the tradition of a classical Hello World implementation) while still covering the most relevant messaging patterns (downstream and upstream messages). For this purpose they make use of simple constant definitions and deal with exceptions as rarely as possible. You may want to change the level of detail that should be logged to the console by editing the contained resources/logback.xml file.\nPlease refer to the JavaDoc of the classes for details.\nInfo Note that production ready code likely has to think more about error handling and logging than this simple blueprint.\nConfigure the Example For simplicity, all configurations are defined as Java constants inside the class HonoExampleConstants.\nIf you have Hono running in Docker under localhost, the example should work out of the box.\nSome configuration values can be overridden by providing them as property to the application.\nThis includes the host and the port of the AMQP network. In the standard setup of Hono they should be configured to the qdrouter from the Apache Qpid project. In production scenarios this might be a large setup of AMQP routers, brokers, etc.\nPlease refer to the class HonoExampleConstants to find out which part of the application can be configured by properties.\nRun the Example The application waits for messages until you press any key or kill it.\nIt is started by\n# in directory: hono/examples/hono-client-examples/ mvn clean package mvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication or (if e.g. the host of the AMQP network should be changed):\nmvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication -Dconsumer.host=192.168.99.100 Telemetry and Event messages Depending on the logger configuration, all received downstream messages are printed to the console.\nPlease note that consumers do not connect with Hono directly, but rather with an AMQP router network.\nCommand and Control By using a helper class provided by Hono, a callback in the application code is invoked when a downstream message was received that signals the device will stay connected to the protocol adapter for some time (see Device notifications for details).\nInside this callback an arbitrary simple command is sent down to the device (once or periodically) and the response is logged to the console.\nEncryption of Communication For the encrypted communication with Hono, the necessary truststore is already installed and used by the Hono client.\nIf you want to integrate the code with your own software, please copy the provided truststore (hono/demo-certs/certs/trusted-certs.pem) from the Hono project to the resources directory of your project and adopt the code pointing to the file location.\nKafka based Messaging To use Kafka based messaging instead of an AMQP network, set the property kafka to true provide the host and port of a bootstrap server:\nmvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication -Dconsumer.host=192.168.99.100 -Dconsumer.port=9092 -Dkafka=true Additional properties for the Kafka producers and consumers can be added in the code, for example to enable encrypted communication. For the available configuration options refer to the Kafka documentation.\n",
    "description": "",
    "tags": null,
    "title": "Consuming Messages from Java",
    "uri": "/hono/docs/2.7/dev-guide/java_client_consumer/"
  },
  {
    "content": "This page provides some hints worth considering when extending the CoAP protocol adapter’s functionality.\nOption Numbers The CoAP adapter uses several of the standard options defined by RFC 7252. Unlike HTTP header fields which are simple strings, the options used in CoAP request and response messages are defined by means of integer numbers. The assignment and registration of option numbers is defined in RFC 7252, Section 12.2. In particular, the RFC reserves the number range 65000-65535 for experimental use.\nWhen adding new Hono specific options to the CoAP adapter, developers are encouraged to use numbers from the 65175-65349 range as discussed and agreed with the Eclipse Californium project.\n",
    "description": "",
    "tags": null,
    "title": "Considerations for extending the CoAP Adapter",
    "uri": "/hono/docs/2.7/dev-guide/coap_adapter/"
  },
  {
    "content": "API Documentation of the APIs defined by Eclipse Hono™.\nFor an overview of the available APIs, see the architecture documentation.\n",
    "description": "",
    "tags": null,
    "title": "API",
    "uri": "/hono/docs/2.7/api/"
  },
  {
    "content": "The Telemetry API is used by Protocol Adapters to send telemetry data downstream. Business Applications and other consumers use the API to receive data published by devices belonging to a particular tenant.\nSee Kafka-based APIs for fundamental information about Hono’s Kafka-based APIs. The statements there apply to this specification.\nSouthbound Operations The following operation can be used by Protocol Adapters to send telemetry data received from devices to downstream consumers like Business Applications.\nProduce Telemetry Data The protocol adapter writes messages to the tenant-specific topic hono.telemetry.${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to upload telemetry data for.\nPreconditions\nEither the topic hono.telemetry.${tenant_id} exists, or the broker is configured to automatically create topics on demand. The client is authorized to write to the topic. The device for which the adapter wants to send telemetry data has been registered (see Device Registration API). Message Flow\nIt is up to the discretion of the protocol adapter whether it wants to use AT LEAST ONCE or AT MOST ONCE delivery semantics according to AT LEAST ONCE Producers respectively AT MOST ONCE Producers.\nThe following sequence diagram illustrates the flow of messages involved in the HTTP Adapter producing a telemetry data message to the Kafka cluster implementing AT MOST ONCE delivery semantics.\nProduce telemetry data flow (AT MOST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter HTTP Adapter produces telemetry data to the Kafka Cluster. HTTP Adapter acknowledges the reception of the data to the Device. The following sequence diagram illustrates the flow of messages involved in the HTTP Adapter producing a telemetry data message to the Kafka cluster implementing AT LEAST ONCE delivery semantics.\nProduce telemetry data flow (AT LEAST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter, indicating QoS Level 1. HTTP Adapter produces telemetry data to the Kafka Cluster. Kafka Cluster acknowledges reception of the message. HTTP Adapter acknowledges the reception of the data to the Device. When a Kafka producer raises an exception while sending a telemetry message to Kafka, the protocol adapter MUST NOT try to re-send such rejected messages but SHOULD indicate the failed transfer to the device if the transport protocol provides means to do so.\nUse AT LEAST ONCE and AT MOST ONCE in a Protocol Adapter\nIf a protocol adapter should support both delivery semantics, a single producer MUST be used and it MUST be configured for AT LEAST ONCE. It may not wait for acknowledgements of AT MOST ONCE messages.\nA protocol adapter MUST NOT use two producers sending telemetry data for the same device. Otherwise, the messages from a device with different QoS levels could be out of order, as Kafka does not guarantee the message order between multiple producer instances.\nMessage Format\nThe key of the message MUST be the device ID.\nMetadata MUST be set as Kafka headers on a message. The following table provides an overview of the headers a client needs to set on a Produce Telemetry Data message.\nName Mandatory Type Description content-type yes string A content type indicating the type and characteristics of the data contained in the message value as a valid MIME type, e.g. text/plain; charset=\"utf-8\" for a text message or application/json etc. The value may be set to application/octet-stream if the message message value is to be considered opaque binary data. See RFC 2046 for details. content-encoding no string The content encoding as defined in section 3.5 of RFC 2616. creation-time yes long The instant in time (UTC, milliseconds since the Unix epoch) when the message has been created. device_id yes string The identifier of the device that the data in the message value is originating from. qos no int The quality of service level of the message. Supported values are 0 for AT MOST ONCE and 1 for AT LEAST ONCE. ttd no int The time ’til disconnect indicates the number of seconds that the device will remain connected to the protocol adapter. The value of this header must be interpreted relative to the message’s creation-time. A value of -1 is used to indicate that the device will remain connected until further notice, i.e. until another message indicates a ttd value of 0. In absence of this property, the connection status of the device is to be considered indeterminate. Backend Applications might use this information to determine a time window during which the device will be able to receive a command. ttl no long The time-to-live in milliseconds. A consumer of the message SHOULD discard the message if the sum of creation-time and ttl is greater than the current time (milliseconds since the Unix epoch). Protocol adapters MAY set additional headers on the Kafka record. Any such headers will be defined in the adapter’s corresponding user guide.\nThe value of the message MUST consist of a byte array containing the telemetry data. The format and encoding of the data MUST be indicated by the content-type and (optional) content-encoding headers of the message.\nNorthbound Operations The following operation can be used by Business Applications to receive telemetry data from Kafka.\nConsume Telemetry Data Hono delivers messages containing telemetry data reported by a particular device in the same order that they have been received in (using the Produce Telemetry Data operation). Business Applications consume messages from the tenant-specific topic hono.telemetry.${tenant_id} where ${tenant_id} represents the ID of the tenant the client wants to retrieve telemetry data for.\nPreconditions\nEither the topic hono.telemetry.${tenant_id} exists, or the broker is configured to automatically create topics on demand. The client is authorized to read from the topic. The client subscribes to the topic with a Kafka consumer. A consumer can provide AT MOST ONCE or AT LEAST ONCE delivery semantics depending on the offset commit strategy it implements. If a message has the qos Kafka header with the value 1, the consumer is expected to provide proper AT LEAST ONCE semantics, and therefore MUST NOT commit the message offset before it has been fully processed.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Business Application consuming a telemetry data message from the Kafka cluster. The delivery mode used is AT LEAST ONCE.\nConsume Telemetry Data Business Application polls telemetry messages from Kafka Cluster. Kafka Cluster returns a batch of messages. Business Application processes the messages. Business Application commits the offset of the last processed telemetry message. Kafka Cluster acknowledges the commit. Message Format\nThe format of the messages containing the telemetry data is the same as for the Produce Telemetry Data operation.\n",
    "description": "",
    "tags": null,
    "title": "Telemetry API Specification for Kafka",
    "uri": "/hono/docs/2.7/api/telemetry-kafka/"
  },
  {
    "content": "The Event API is used by Protocol Adapters to send event messages downstream. Business Applications and other consumers use the API to receive messages published by devices belonging to a particular tenant.\nSee Kafka-based APIs for fundamental information about Hono’s Kafka-based APIs. The statements there apply to this specification.\nSouthbound Operations The following operation can be used by Protocol Adapters to send event messages received from devices to downstream consumers like Business Applications.\nProduce Event The protocol adapter writes messages to the tenant-specific topic hono.event.${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to upload event messages for.\nPreconditions\nEither the topic hono.event.${tenant_id} exists, or the broker is configured to automatically create topics on demand. The client is authorized to write to the topic. The device for which the adapter wants to send event messages has been registered (see Device Registration API). Message Flow\nHono supports AT LEAST ONCE delivery of Event messages only, as defined in Kafka-based APIs.\nThe following sequence diagram illustrates the flow of messages involved in the MQTT Adapter producing an event to the Kafka cluster.\nProduce event flow Device 4711 publishes an event using MQTT QoS 1. MQTT Adapter produces an event message to the Kafka Cluster. Kafka cluster acknowledges reception of the message. MQTT Adapter acknowledges the reception of the message to the Device. When a Kafka producer raises an exception while sending an event message to Kafka, the protocol adapter MUST NOT try to re-send such rejected messages but MUST indicate the failed transfer to the device if the transport protocol provides means to do so.\nMessage Format\nSee Telemetry API for Kafka for the definition of the message format.\nNorthbound Operations The following operation can be used by Business Applications to receive event messages from Kafka.\nConsume Events Hono delivers messages containing events reported by a particular device in the same order that they have been received in (using the Produce Event operation). Business Applications consume messages from the tenant-specific topic hono.event.${tenant_id} where ${tenant_id} represents the ID of the tenant the client wants to retrieve event messages for.\nPreconditions\nEither the topic hono.event.${tenant_id} exists, or the broker is configured to automatically create topics on demand. The client is authorized to read from the topic. The client subscribes to the topic with a Kafka consumer. Hono supports AT LEAST ONCE delivery of Event messages only. A consumer is expected to provide proper AT LEAST ONCE semantics and therefore MUST NOT commit offsets of messages that have not yet been fully processed.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Business Application consuming an event message from the Kafka cluster.\nConsume event flow (success) Business Application polls event messages from Kafka Cluster. Kafka Cluster returns a batch of messages. Business Application processes the messages. Business Application commits the offset of the last processed event message. Kafka Cluster acknowledges the commit. Message Format\nSee Telemetry API for Kafka for the definition of the message format.\nWell-known Event Message Types The well-known event message types are defined in the Event API for AMQP with the following differences:\nThe properties and application-properties are set es Kafka headers. The body of the AMQP message corresponds to the value of the Kafka message. The content-type header is of type string. ",
    "description": "",
    "tags": null,
    "title": "Event API Specification for Kafka",
    "uri": "/hono/docs/2.7/api/event-kafka/"
  },
  {
    "content": "The Command \u0026 Control API of Eclipse Hono™ is used by Business Applications to send commands to connected devices.\nCommands can be used to trigger actions on devices. Examples include updating a configuration property, installing a software component or switching the state of an actuator.\nHono distinguishes two types of commands. The first type is one-way only. In this case the sender of the command does not expect the device to send back a message in response to the command. This type of command is referred to as a one-way command in the remainder of this page. One-way commands may be used to e.g. notify a device about a change of state.\nThe second type of commands expects a response to be sent back from the device as a result of processing the command. In this case the response contains a status code which indicates whether the command could be processed successfully. If so, the response may also include data representing the result of processing the command. This type of command is plainly referred to as a command because it represents the default case.\nSee Kafka-based APIs for fundamental information about Hono’s Kafka-based APIs. The statements there apply to this specification.\nSend a One-Way Command Business Applications use this operation to send a command to a device for which they do not expect to receive a response from the device. For that, the Business Application connects to the Kafka Cluster and writes a message to the tenant-specific topic hono.command.${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to send the command for.\nPreconditions\nEither the topic hono.command.${tenant_id} exists, or the broker is configured to automatically create topics on demand. The Business Application is authorized to write to the topic. Message Flow\nThe Business Application writes a command message to the topic hono.command.${tenant_id} on the Kafka Cluster. Hono consumes the message from the Kafka Cluster and forwards it to the device, provided that the target device is connected and is accepting commands. Message Format\nThe key of the message MUST be the ID of the device that the command is targeted at.\nMetadata MUST be set as Kafka headers on a message. The following table provides an overview of the headers the Business Application needs to set on a one-way command message.\nName Mandatory Type Description device_id yes string The identifier of the device that the command is targeted at. subject yes string The name of the command to be executed by the device. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. The command message MAY contain arbitrary payload, set as message value, to be sent to the device. The value of the message’s subject header may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nSend a (Request/Response) Command Business Applications use this operation to send a command to a device for which they expect the device to send back a response. For that, the Business Application connects to the Kafka Cluster and writes a message to the tenant-specific topic hono.command.${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to send the command for. The Business Application can consume the corresponding command response from the hono.command_response.${tenant_id} topic.\nIn contrast to a one-way command, a request/response command contains a response-required header with value true and a correlation-id header, providing the identifier that is used to correlate a response message to the original request.\nPreconditions\nEither the topics hono.command.${tenant_id} and hono.command_response.${tenant_id} exist, or the broker is configured to automatically create topics on demand. The Business Application is authorized to write to the hono.command.${tenant_id} topic and read from the hono.command_response.${tenant_id} topic. The Business Application is subscribed to the hono.command_response.${tenant_id} topic with a Kafka consumer. Message Flow\nThe Business Application writes a command message to the topic hono.command.${tenant_id} on the Kafka Cluster. Hono consumes the message from the Kafka Cluster and forwards it to the device, provided that the target device is connected and is accepting commands. The device sends a command response message. Hono writes that message to the hono.command_response.${tenant_id} topic on the Kafka Cluster. The Business Application consumes the command response message from the hono.command_response.${tenant_id} topic. Command Message Format\nThe key of the message MUST be the ID of the device that the command is targeted at.\nMetadata MUST be set as Kafka headers on a message. The following table provides an overview of the headers the Business Application needs to set on a request/response command message.\nName Mandatory Type Description correlation-id yes string The identifier used to correlate a response message to the original request. It is used as the correlation-id header in the response. device_id yes string The identifier of the device that the command is targeted at. response-required yes boolean MUST be set with a value of true, meaning that the device is required to send a response for the command. subject yes string The name of the command to be executed by the device. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. delivery-failure-notification-metadata[*] no string Headers with the delivery-failure-notification-metadata prefix are adopted for the error command response that is sent in case delivering the command to the device failed. In case of a successful command delivery, these headers are ignored. The command message MAY contain arbitrary payload, set as message value, to be sent to the device. The value of the message’s subject header may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nAn application can determine the overall outcome of the operation by means of the response to the command. The response is either sent back by the device, or in case the command could not be successfully forwarded to the device, an error command response message is sent by the Hono protocol adapter or Command Router component.\nResponse Message Format\nThe key of the message MUST be the ID of the device that the command response is from.\nMetadata MUST be set as Kafka headers on a message. The following table provides an overview of the headers set on a message sent in response to a command.\nName Mandatory Type Description correlation-id yes string MUST contain the value of the correlation-id header of the request message that this is the response for. creation-time yes long The instant in time (milliseconds since the Unix epoch) when the message has been created. device_id yes string The identifier of the device that sent the response. status yes integer MUST indicate the status of the execution. See table below for possible values. tenant_id yes string The identifier of the tenant that the device belongs to. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.\nIf the response is an error message sent by the Hono protocol adapter or Command Router component, the content type MUST be application/vnd.eclipse-hono-delivery-failure-notification+json. delivery-failure-notification-metadata[*] no string MUST be adopted from the command message headers with the same names if the response is an error message sent by the Hono protocol adapter or Command Router component. The status header must contain an HTTP 1.1 response status code.\nThe command response message MAY contain arbitrary payload, set as message value, to be sent to the business application.\nResponse Message sent from Device\nIn a response from a device, the semantics of the status code ranges are as follows:\nCode Description 2xx The command has been processed successfully. 4xx The command could not be processed due to a client error, e.g. malformed message payload. 5xx The command could not be processed due to an internal problem at the device side. The semantics of the individual codes are specific to the device and command. For status codes indicating an error (codes in the 400 - 599 range) the message body MAY contain a detailed description of the error that occurred.\nResponse Message sent from Hono Component\nIf the command response message represents an error message sent by the Hono protocol adapter or Command Router component, with the content-type header set to application/vnd.eclipse-hono-delivery-failure-notification+json, the possible status codes are:\nCode Description 4xx The command has not been delivered to or processed by the device because the command message does not contain all required information. Another reason may be that a message limit has been exceeded. 5xx The command has not been delivered to the device or can not be processed by the device due to reasons that are not the responsibility of the sender of the command. Possible reasons are:The device is (currently) not connected.In case the transport protocol supports acknowledgements: The device hasn’t sent an acknowledgement in time or has indicated that the message cannot be processed.There was an error forwarding the command to the device. The payload MUST contain a UTF-8 encoded string representation of a single JSON object with the following fields:\nName Mandatory Type Description error yes string The error message describing the cause for the command message delivery failure. ",
    "description": "",
    "tags": null,
    "title": "Command \u0026 Control API Specification for Kafka",
    "uri": "/hono/docs/2.7/api/command-and-control-kafka/"
  },
  {
    "content": "The Kafka-based APIs of Eclipse Hono™ provide an alternative to the existing APIs based on AMQP 1.0. With these APIs, clients publish data to as well as consume data from an Apache Kafka® cluster instead of using an AMQP messaging network.\nKafka-based Messaging Using Kafka instead of AMQP comes with slightly different behavior. Kafka provides a Publish/Subscribe messaging style. Every message is sent by a producer to a topic in a Kafka cluster, where it will be persisted by (multiple) brokers. Each topic consists of a configurable number of partitions. The key of a message determines to which partition it will be written. Each partition is replicated to a configurable number of brokers in the cluster to provide fault-tolerance if a broker goes down.\nA Kafka message (also called record) consists of a key, a value, a timestamp, and headers.\nMultiple consumers can read the messages at the same time and they can read them repeatedly (if an error occurred). This decoupling of producer and consumers has the consequence that a producer does not get feedback about the consumption of messages, it does not know if and when a message will be read by any consumer(s). For example, a protocol adapter can only confirm to the device that the Kafka cluster successfully persisted a telemetry message, not if a Business Application received it.\nMessages are usually deleted from a topic at some point – regardless of whether they have been processed by a consumer. Care should therefore be taken to set each topic’s log retention time to a reasonable value in the Kafka configuration.\nSee the Kafka documentation for details about Kafka’s configuration properties.\nQuality of Service The Kafka client’s acks configuration property is used to configure what acknowledgements a producer expects from the cluster for each message. The value of this property determines the maximum Quality of Service level the producer can achieve. Kafka supports the following settings:\n0: the producer does not wait for any acknowledgements. This provides no guarantees. 1: the producer requests only an acknowledgement from one broker. If the broker goes down before others finished replication, then the message will be lost. all (or equivalent -1): the producer requests an acknowledgement that confirms that the message has successfully been replicated to the required number of brokers. This guarantees that the message will not be lost as long as at least one of the replicas remains alive. Message Ordering For each partition of a topic, Kafka guarantees that consumers receive messages in the same order that the producer has written them to the partition. Hono’s protocol adapters, therefore, use the device identifier as the key when writing messages to downstream topics, thus making sure that messages originating from the same device always end up in the same partition. For example, each protocol adapter must always send telemetry data reported by a particular device to the same partition (e.g. by using the same partitioner implementation) in the same order that they have been received in.\nThe following producer configuration properties influence if the order of the messages can be guaranteed by Kafka:\nretries max.in.flight.requests.per.connection enable.idempotence Setting acks to 0 effectively disables retries. If retries are set to a value greater than zero and max.in.flight.requests.per.connection is set to a value greater than 1, Kafka no longer guarantees that messages are stored in the order they have been sent. The only exception is the idempotent producer, which can handle max.in.flight.requests.per.connection to be up to 5 with retries enabled while still maintaining the message order (since Kafka version 1.0.0). Note that the idempotent producer option requires special privileges for the producer’s user to be configured.\nAT LEAST ONCE Producers To provide AT LEAST ONCE delivery semantics, a producer MUST wait for the acknowledgements from all in-sync replicas before sending the acknowledgement back to the client. This can be achieved e.g. by setting acks to all or, implicitly, by setting enable.idempotence to true.\nThe producer MUST retain the order in which it received messages from a client. This requires that if retries is set to a value greater than zero, max.in.flight.requests.per.connection must be set to 1. Alternatively, enable.idempotence can be set to true. Disabling retries might cause messages to fail in case of high load or transient transmission failures, so this is not recommended.\nThe recommended configuration for AT LEAST ONCE producers has the following properties: enable.idempotence=true, acks=all, max.in.flight.requests.per.connection=5, leaving retries unset (which defaults to Integer.MAX), and setting delivery.timeout.ms to a reasonable value. This configuration is supported from Kafka version 1.0.0 on.\nAT MOST ONCE Producers Every producer that does not wait for acknowledgements from all in-sync replicas or does not consider them before sending an acknowledgement back to the client, is considered to provide only AT MOST ONCE delivery semantics. To achieve this, several strategies are possible:\nThe producer can disable acknowledgements (acks=0). This is the fastest mode of delivery but has the drawback of a potential loss of messages without notice. The producer can enable acknowledgements, but not wait for the acknowledgements from the Kafka cluster before acknowledging the message to its client. The producer MUST retain the order in which it received messages from a client. This requires to either set retries to 0 or to set max.in.flight.requests.per.connection to 1.\nTip To send messages with both delivery semantics with the same producer, it MUST be configured for AT LEAST ONCE. Such a producer may ignore the outcome of the produce operation for AT MOST ONCE messages.\n",
    "description": "",
    "tags": null,
    "title": "Kafka-based APIs",
    "uri": "/hono/docs/2.7/api/kafka-api/"
  },
  {
    "content": "The Telemetry API is used by Protocol Adapters to send telemetry data downstream. Business Applications and other consumers use the API to receive data published by devices belonging to a particular tenant.\nThe Telemetry API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use AMQP when referring to AMQP 1.0.\nThe Telemetry API for AMQP 1.0 is an alternative to the Telemetry API for Kafka for applications that want to consume telemetry data from an AMQP Messaging Network instead of an Apache Kafka™ broker.\nSouthbound Operations The following operations can be used by Protocol Adapters to forward telemetry data received from devices to downstream consumers like Business Applications.\nForward Telemetry Data Preconditions\nAdapter has established an AMQP connection with the AMQP Messaging Network. Adapter has established an AMQP link in role sender with the AMQP Messaging Network using target address telemetry/${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to upload telemetry data for. The device for which the adapter wants to send telemetry data has been registered (see Device Registration API). The adapter indicates its preferred message delivery mode by means of the snd-settle-mode and rcv-settle-mode fields of its attach frame during link establishment.\nsnd-settle-mode rcv-settle-mode Delivery semantics unsettled, mixed first Using unsettled for the snd-settle-mode allows for adapters to implement both AT LEAST ONCE or AT MOST ONCE delivery semantics, depending on whether the adapter waits for and considers the disposition frames it receives from the AMQP Messaging Network or not. This is the recommended mode for forwarding telemetry data. settled first Using settled for the snd-settle-mode allows for adapters to implement AT MOST ONCE delivery semantics only. This is the fastest mode of delivery but has the drawback of less reliable end-to-end flow control and potential loss of messages without notice. All other combinations are not supported by Hono and may result in the termination of the link or connection (depending on the configuration of the AMQP Messaging Network).\nMessage Flow\nAs indicated above, it is up to the discretion of the protocol adapter whether it wants to use AT LEAST ONCE or AT MOST ONCE delivery semantics.\nHono’s HTTP adapter allows devices to indicate, which delivery semantics they want to use when uploading telemetry data. The HTTP adapter always forwards messages unsettled and either ignores the outcome of the message transfer (AT MOST ONCE) or waits for the downstream peer to accept the message (AT LEAST ONCE) before acknowledging the reception of the message to the device.\nThe following sequence diagram illustrates the flow of messages involved in the HTTP Adapter forwarding an unsettled telemetry data message to the downstream AMQP Messaging Network implementing AT MOST ONCE delivery semantics.\nForward telemetry data flow (AT MOST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter HTTP Adapter transfers telemetry data to AMQP 1.0 Messaging Network. HTTP Adapter acknowledges the reception of the data to the Device. AMQP 1.0 Messaging Network acknowledges reception of the message which is ignored by the HTTP Adapter. Info In the example above the HTTP adapter does not wait for the outcome of the transfer of the message to the AMQP Messaging Network before sending back the HTTP response to the device. If the messaging network had sent a disposition frame with the rejected instead of the accepted outcome, the HTTP adapter would still have signaled a 202 status code back to the device. In this case the data would have been lost without the device noticing.\nThe following sequence diagram illustrates the flow of messages involved in the HTTP Adapter forwarding an unsettled telemetry data message to the downstream AMQP Messaging Network implementing AT LEAST ONCE delivery semantics.\nForward telemetry data flow (AT LEAST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter, indicating QoS Level 1. HTTP Adapter transfers telemetry data to AMQP 1.0 Messaging Network. AMQP 1.0 Messaging Network acknowledges reception of the message. HTTP Adapter acknowledges the reception of the data to the Device. When the AMQP Messaging Network fails to settle the transfer of a telemetry message or settles the transfer with any other outcome than accepted, the protocol adapter MUST NOT try to re-send such rejected messages but SHOULD indicate the failed transfer to the device if the transport protocol provides means to do so.\nMessage Format\nThe following table provides an overview of the properties a client needs to set on a Forward Telemetry Data message.\nName Mandatory Location Type Description content-type yes properties symbol A content type indicating the type and characteristics of the data contained in the payload, e.g. text/plain; charset=\"utf-8\" for a text message or application/json etc. The value may be set to application/octet-stream if the message payload is to be considered opaque binary data. creation-time yes properties timestamp The instant in time when the message has been created (see the AMQP 1.0 specification for details). device_id yes application-properties string The identifier of the device that the data in the payload is originating from. ttd no application-properties int The time ’til disconnect indicates the number of seconds that the device will remain connected to the protocol adapter. The value of this property must be interpreted relative to the message’s creation-time. A value of -1 is used to indicate that the device will remain connected until further notice, i.e. until another message indicates a ttd value of 0. In absence of this property, the connection status of the device is to be considered indeterminate. Backend Applications might use this information to determine a time window during which the device will be able to receive a command. Protocol adapters MAY set additional properties or application-properties on a downstream message. Any such properties will be defined in the adapter’s corresponding user guide.\nThe body of the message MUST consist of a single AMQP Data section containing the telemetry data. The format and encoding of the data MUST be indicated by the content-type and (optional) content-encoding properties of the message.\nNorthbound Operations Receive Telemetry Data Hono delivers messages containing telemetry data reported by a particular device in the same order that they have been received in (using the Forward Telemetry Data operation). Hono MAY drop telemetry messages that it cannot deliver to any consumers. Reasons for this include that there are no consumers connected to Hono or the existing consumers are not able to process the messages from Hono fast enough.\nHono supports multiple non-competing Business Application consumers of telemetry data for a given tenant. Hono allows each Business Application to have multiple competing consumers for telemetry data for a given tenant to share the load of processing the messages.\nPreconditions\nClient has established an AMQP connection with Hono. Client has established an AMQP link in role receiver with Hono using source address telemetry/${tenant_id} where ${tenant_id} represents the ID of the tenant the client wants to retrieve telemetry data for. Hono supports both AT MOST ONCE as well as AT LEAST ONCE delivery of telemetry messages. However, clients SHOULD use AT LEAST ONCE delivery in order to support end-to-end flow control and therefore SHOULD set the snd-settle-mode field to unsettled and the rcv-settle-mode field to first in their attach frame during link establishment.\nA client MAY indicate to Hono during link establishment that it wants to distribute the telemetry messages received for a given tenant among multiple consumers by including a link property subscription-name whose value is shared by all other consumers of the tenant. Hono ensures that messages from a given device are delivered to the same consumer. Note that this also means that telemetry messages MAY not be evenly distributed among consumers, e.g. when only a single device sends data. NB This feature is not supported yet.\nIn addition a client MAY include a boolean link property ordering-required with value false during link establishment in order to indicate to Hono that it does not require messages being delivered strictly in order per device but instead allows for messages being distributed evenly among the consumers. NB This feature is not supported yet.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Business Application receiving a telemetry data message from Hono. The delivery mode used is AT LEAST ONCE.\nReceive Telemetry Data AMQP 1.0 Messaging Network delivers telemetry message to Business Application. Business Application acknowledges reception of message. Info The Business Application can only consume telemetry messages that have been uploaded to Hono after the Business Application has established the link with the AMQP 1.0 Messaging Network. This is because telemetry messages are not durable, i.e. they are not persisted in Hono in order to be forwarded at a later time.\nMessage Format\nThe format of the messages containing the telemetry data is the same as for the Forward Telemetry Data operation.\n",
    "description": "",
    "tags": null,
    "title": "Telemetry API Specification for AMQP 1.0",
    "uri": "/hono/docs/2.7/api/telemetry/"
  },
  {
    "content": "The Event API is used by Protocol Adapters to send event messages downstream. Business Applications and other consumers use the API to receive messages published by devices belonging to a particular tenant.\nThe Event API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use AMQP when referring to AMQP 1.0.\nThe Event API for AMQP 1.0 is an alternative to the Event API for Kafka for applications that want to consume events from an AMQP Messaging Network instead of an Apache Kafka™ broker.\nSouthbound Operations The following operations can be used by Protocol Adapters to forward event messages received from devices to downstream consumers like Business Applications.\nForward Event Preconditions\nAdapter has established an AMQP connection with the AMQP Messaging Network. Adapter has established an AMQP link in role sender with the AMQP Messaging Network using target address event/${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to upload event messages for. The device for which the adapter wants to send an event has been registered (see Device Registration API). Hono supports AT LEAST ONCE delivery of Event messages only. A client therefore MUST use unsettled for the snd-settle-mode and first for the rcv-settle-mode fields of its attach frame during link establishment. All other combinations are not supported by Hono and may result in the termination of the link or connection (depending on the configuration of the AMQP Messaging Network).\nThe AMQP messages used to forward events to the AMQP Messaging Network MUST have their durable property set to true. The AMQP Messaging Network is expected to write such messages to a persistent store before settling the transfer with the accepted outcome.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in the MQTT Adapter forwarding an event to the downstream AMQP Messaging Network.\nForward event flow Device 4711 publishes an event using MQTT QoS 1. MQTT Adapter transfers data to AMQP 1.0 Messaging Network. AMQP 1.0 Messaging Network acknowledges reception of the message. MQTT Adapter acknowledges the reception of the message to the Device. When the AMQP Messaging Network fails to settle the transfer of an event message or settles the transfer with any other outcome than accepted, the protocol adapter MUST NOT try to re-send such rejected messages but MUST indicate the failed transfer to the device if the transport protocol provides means to do so.\nMessage Format\nSee Telemetry API for definition of message format.\nNorthbound Operations Receive Events Hono delivers messages containing events reported by a particular device in the same order that they have been received in (using the Forward Event operation).\nHono supports multiple non-competing Business Application consumers of event messages for a given tenant. Hono allows each Business Application to have multiple competing consumers for event messages for a given tenant to share the load of processing the messages.\nPreconditions\nClient has established an AMQP connection with Hono. Client has established an AMQP link in role receiver with Hono using source address event/${tenant_id} where ${tenant_id} represents the ID of the tenant the client wants to retrieve event messages for. Hono supports AT LEAST ONCE delivery of Event messages only. A client therefore MUST use unsettled for the snd-settle-mode and first for the rcv-settle-mode fields of its attach frame during link establishment. All other combinations are not supported by Hono and result in the termination of the link.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Business Application receiving an event message from Hono.\nReceive event data flow (success) AMQP 1.0 Messaging Network delivers event message to Business Application. Business Application acknowledges reception of message. Message Format\nSee Telemetry API for definition of message format.\nWell-known Event Message Types Hono defines several well-known event types which have specific semantics. Events of these types are identified by means of the AMQP message’s content-type.\nEmpty Notification An AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.\nThe AMQP 1.0 properties an event sender needs to set for an empty notification event are defined in the Telemetry API.\nThe relevant properties are listed again in the following table:\nName Mandatory Location Type Description content-type yes properties symbol MUST be set to application/vnd.eclipse-hono-empty-notification ttd no application-properties int The time ’til disconnect as described in the Telemetry API. Tip An empty notification can be used to indicate to a Business Application that a device is currently ready to receive an upstream message by setting the ttd property. Backend Applications may use this information to determine the time window during which the device will be able to receive a command.\nConnection Event Protocol Adapters may send this type of event to indicate that a connection with a device has been established or has ended. Note that such events can only be sent for authenticated devices, though, because an event is always scoped to a tenant and the tenant of a device is established as part of the authentication process.\nThe AMQP message for a connection event MUST contain the following properties in addition to the standard event properties:\nName Mandatory Location Type Description content-type yes properties symbol Must be set to application/vnd.eclipse-hono-dc-notification+json device_id yes application-properties string The ID of the authenticated device Each connection event’s payload MUST contain a UTF-8 encoded string representation of a single JSON object with the following fields:\nName Mandatory Type Description cause yes string The cause of the connection event. MUST be set to either connected or disconnected. remote-id yes string An identifier of the device that is the subject of this event, e.g. an IP address:port, client id etc. The format and semantics of this identifier is specific to the protocol adapter and the transport protocol it supports. source yes string The type name of the protocol adapter reporting the event, e.g. hono-mqtt. data no object An arbitrary JSON object which may contain additional information about the occurrence of the event. The example below might be used by the MQTT adapter to indicate that a connection with a device using client identifier mqtt-client-id-1 has been established:\n{ \"cause\": \"connected\", \"remote-id\": \"mqtt-client-id-1\", \"source\": \"hono-mqtt\", \"data\": { \"foo\": \"bar\" } } Device Provisioning Notification Device registries may send this event to convey provisioning related changes regarding a device. This may be used as a hook for north bound applications if further application specific logic should be implemented upon provisioning changes.\nAn AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.\nThe relevant properties are listed again in the following table:\nName Mandatory Location Type Description content-type yes properties symbol MUST be set to application/vnd.eclipse-hono-device-provisioning-notification hono_registration_status yes application-properties string Contains NEW if the device has been newly provisioned. tenant_id yes application-properties string The tenant id denoting the tenant of the device. device_id yes application-properties string The id of the device. gateway_id no application-properties string This property contains a value only if the device’s registration status has been changed by a gateway acting on behalf of the device. In such a case, the property contains the identifier of the gateway, otherwise the property will not be included. ",
    "description": "",
    "tags": null,
    "title": "Event API Specification for AMQP 1.0",
    "uri": "/hono/docs/2.7/api/event/"
  },
  {
    "content": "The Command \u0026 Control API of Eclipse Hono™ is used by Business Applications to send commands to connected devices.\nCommands can be used to trigger actions on devices. Examples include updating a configuration property, installing a software component or switching the state of an actuator.\nHono distinguishes two types of commands. The first type is one-way only. In this case the sender of the command does not expect the device to send back a message in response to the command. This type of command is referred to as a one-way command in the remainder of this page. One-way commands may be used to e.g. notify a device about a change of state.\nThe second type of commands expects a response to be sent back from the device as a result of processing the command. In this case the response contains a status code which indicates whether the command could be processed successfully. If so, the response may also include data representing the result of processing the command. This type of command is plainly referred to as a command because it represents the default case.\nThe Command \u0026 Control API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use AMQP when referring to AMQP 1.0.\nThe Command \u0026 Control API for AMQP 1.0 is an alternative to the Command \u0026 Control API for Kafka for applications that want to use an AMQP 1.0 Messaging Network instead of an Apache Kafka™ broker to send command messages to devices.\nSend a One-Way Command Business Applications use this operation to send a command to a device for which they do not expect to receive a response from the device.\nPreconditions\nThe Business Application has established an AMQP connection with the AMQP 1.0 Network. The Business Application has established an AMQP link in role sender with the target address command/${tenant_id}, where ${tenant_id} is the ID of the tenant that the device belongs to. This link is used by the Business Application to send command messages. The following sequence diagram illustrates the establishment of the required link:\nApplication connecting to the AMQP 1.0 Messaging Network Message Format\nThe following table provides an overview of the properties the Business Application needs to set on a one-way command message.\nName Mandatory Location Type Description to yes properties string MUST contain the target address command/${tenant_id}/${device_id} of the message, where ${device_id} is the ID of the device to send the message to. subject yes properties string The name of the command to be executed by the device. content-type no properties string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. message-id no properties string An identifier that uniquely identifies the message at the sender side. The command message MAY contain arbitrary payload to be sent to the device in a single AMQP Data section. The value of the message’s subject property may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nHono indicates the outcome of the operation by means of the following AMQP delivery states:\nDelivery State Description accepted The command has been delivered to the device for processing. released The command has not been delivered to the device or can not be processed by the device due to reasons that are not the responsibility of the sender of the command. Possible reasons are:The device is (currently) not connected.In case the transport protocol supports acknowledgements: The device hasn’t sent an acknowledgement in time or has indicated that the message cannot be processed.There was an error forwarding the command to the device. rejected The command has not been delivered to or processed by the device because the command message does not contain all required information. Another reason may be that a message limit has been exceeded. Info Hono relies on the particular protocol adapter to deliver commands to devices. Depending on the used transport protocol and the adapter’s implementation, the accepted outcome may thus indicate any of the following:\nAn attempt has been made to deliver the command to the device. However, it is unclear if the device has received (or processed) the command. The device has acknowledged the reception of the command but has not processed the command yet. The device has received and processed the command. Examples\nThe following sequence diagram shows the successful delivery of a one-way command called switchOn to device 4711 of the DEFAULT_TENANT:\nSuccessfully send a One-Way Command The following sequence diagram shows how the delivery of the same one-way command fails because the device is not connected:\nDevice not connected The following sequence diagram illustrates how a malformed command sent by a Business Application gets rejected:\nMalformed Command message Send a (Request/Response) Command Business Applications use this operation to send a command to a device for which they expect the device to send back a response.\nPreconditions\nThe Business Application has established an AMQP connection with the AMQP 1.0 Network. The Business Application has established an AMQP link in role sender with the target address command/${tenant_id}, where ${tenant_id} is the ID of the tenant that the device belongs to. This link is used by the Business Application to send command messages. The Business Application has established an AMQP link in role receiver with the source address command_response/${tenant_id}/${reply_id}. This link is used by the Business Application to receive the response to the command from the device. This link’s source address is also used as the reply-to address for the request messages. The ${reply_id} may be any arbitrary string chosen by the application. The following sequence diagram illustrates the establishment of the required links:\nApplication connecting to the AMQP 1.0 Messaging Network Command Message Format\nThe following table provides an overview of the properties the Business Application needs to set on a command message.\nName Mandatory Location Type Description to yes properties string MUST contain the target address command/${tenant_id}/${device_id} of the message, where ${device_id} is the ID of the device to send the message to. subject yes properties string MUST contain the command name to be executed by a device. content-type no properties string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. correlation-id no properties string MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the application expects to receive the response from. This address MUST be the same as the source address used for establishing the client’s receiver link (see Preconditions above). The command message MAY contain arbitrary payload to be sent to the device in a single AMQP Data section. The value of the command message’s subject value may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nHono uses following AMQP delivery states to indicate the outcome of sending the command to the device:\nDelivery State Description accepted The command has been delivered to the device for processing. released The command has not been delivered to the device or can not be processed by the device due to reasons that are not the responsibility of the sender of the command. Possible reasons are:The device is (currently) not connected.In case the transport protocol supports acknowledgements: The device hasn’t sent an acknowledgement in time or has indicated that the message cannot be processed.There was an error forwarding the command to the device. rejected The command has not been delivered to or processed by the device because the command message does not contain all required information. Another reason may be that a message limit has been exceeded. Info Hono relies on the particular protocol adapter to deliver commands to devices. Depending on the used transport protocol and the adapter’s implementation, the accepted outcome may thus indicate any of the following:\nAn attempt has been made to deliver the command to the device. However, it is unclear if the device has received (or processed) the command. The device has acknowledged the reception of the command but has not processed the command yet. An application can determine the overall outcome of the operation by means of the response to the command that is sent back by the device. An application should consider execution of a command to have failed, if it does not receive a response within a reasonable amount of time.\nResponse Message Format\nThe following table provides an overview of the properties set on a message sent in response to a command.\nName Mandatory Location Type Description content-type no properties string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. correlation-id yes properties string MUST contain the correlation ID used to match the command message with the response message containing the result of execution on the device. creation-time yes properties timestamp The instant in time when the message has been created (see the AMQP 1.0 specification for details). device_id yes application-properties string The identifier of the device that sent the response. status yes application-properties int MUST indicate the status of the execution. See table below for possible values. tenant_id yes application-properties string The identifier of the tenant that the device belongs to. The status property must contain an HTTP 1.1 response status code:\nCode Description 2xx The command has been processed successfully. 4xx The command could not be processed due to a client error, e.g. malformed message payload. 5xx The command could not be processed due to an internal problem at the device side. The semantics of the individual codes are specific to the device and command. For status codes indicating an error (codes in the 400 - 599 range) the message body MAY contain a detailed description of the error that occurred.\nIf a command message response contains a payload, the body of the message MUST consist of a single AMQP Data section containing the response message data.\nExamples\nThe following sequence diagram illustrates how a Business Application sends a command called getReading to device 4711 of the DEFAULT_TENANT and receives a response from the device:\nSuccessfully send a Command The sending of a command may fail for the same reasons as those illustrated for sending a one-way command. Additionally, the sending of a command may be considered unsuccessful by an application if it does not receive the response from the device in a reasonable amount of time:\nCommand times out ",
    "description": "",
    "tags": null,
    "title": "Command \u0026 Control API Specification for AMQP 1.0",
    "uri": "/hono/docs/2.7/api/command-and-control/"
  },
  {
    "content": "The Telemetry API is used by Protocol Adapters to send telemetry data downstream. Business Applications and other consumers use the API to receive data published by devices belonging to a particular tenant.\nThe Telemetry API is defined by means of Google Pub/Sub message exchanges, i.e. a client needs to connect to Hono and configure Hono for Google Pub/Sub messaging infrastructure in order to use it and invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use Pub/Sub when referring to Google Pub/Sub.\nThe Telemetry API for Pub/Sub is an alternative to the Telemetry API for Kafka for applications that want to consume telemetry data from Pub/Sub instead of an Apache Kafka™ broker.\nWarning Support for the Google Pub/Sub based Telemetry API is considered experimental and may change without further notice.\nSouthbound Operations The following operation can be used by Protocol Adapters to publish telemetry data received from devices to consumers like Business Applications.\nPublish Telemetry Data The protocol adapter writes messages to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.telemetry where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant that the client wants to upload telemetry data for.\nPreconditions\nA Google Cloud Project is set up with the Pub/Sub API enabled. The ID of the Google Cloud Project is declared as mentioned in the Publisher Configuration. The client is authorized to write to the topic. The device for which the adapter wants to send telemetry data has been registered (see Device Registration API). Message Flow\nIt is up to the discretion of the protocol adapter whether it wants to use AT LEAST ONCE or AT MOST ONCE delivery semantics.\nThe following sequence diagram illustrates the flow of messages involved in the HTTP Adapter publishing a telemetry data message to the Pub/Sub API implementing AT MOST ONCE delivery semantics.\nPublish telemetry data flow (AT MOST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter HTTP Adapter publishes telemetry data to the Pub/Sub API. HTTP Adapter acknowledges the reception of the data to the Device. The following sequence diagram illustrates the flow of messages involved in the HTTP Adapter publishing a telemetry data message to the Pub/Sub API implementing AT LEAST ONCE delivery semantics.\nPublish telemetry data flow (AT LEAST ONCE) Device 4711 PUTs telemetry data to the HTTP Adapter, indicating QoS Level 1. HTTP Adapter publishes telemetry data to the Pub/Sub API. Pub/Sub acknowledges reception of the message. HTTP Adapter acknowledges the reception of the data to the Device. When a Pub/Sub publisher raises an exception while sending a telemetry message to Pub/Sub, the protocol adapter MUST NOT try to re-send such rejected messages but SHOULD indicate the failed transfer to the device if the transport protocol provides means to do so.\nMessage Format\nThe following table provide an overview of the relevant properties of the message format for a Pub/Sub message as defined in the Google Pub/Sub Documentation. The message must contain a non-empty data field or at least one attribute (or both).\nName Type Description data string The message data field contains the base64-encoded string representation of the payload. attributes map Attributes for this message, which can be used to filter messages on the subscription. orderingKey string Identifies related messages for which publish order should be respected. If a Subscription has enableMessageOrdering set to true, messages published with the same non-empty orderingKey value will be delivered to subscribers in the order in which they are received by the Pub/Sub system. The orderingKey MUST be the device ID. Metadata MUST be set as attributes on a Pub/Sub message. The following table provides an overview a client needs to set on a Publish Telemetry Data message.\nName Mandatory Type Description content-type yes string A content type indicating the type and characteristics of the data contained in the message value as a valid MIME type, e.g. text/plain; charset=\"utf-8\" for a text message or application/json etc. The value may be set to application/octet-stream if the message message value is to be considered opaque binary data. See RFC 2046 for details. content-encoding no string The content encoding as defined in section 3.5 of RFC 2616. creation-time yes long The instant in time (UTC, milliseconds since the Unix epoch) when the message has been created. device_id yes string The identifier of the device that the data in the message value is originating from. qos no int The quality of service level of the message. Supported values are 0 for AT MOST ONCE and 1 for AT LEAST ONCE. ttd no int The time ’til disconnect indicates the number of seconds that the device will remain connected to the protocol adapter. The value of this header must be interpreted relative to the message’s creation-time. A value of -1 is used to indicate that the device will remain connected until further notice, i.e. until another message indicates a ttd value of 0. In absence of this property, the connection status of the device is to be considered indeterminate. Backend Applications might use this information to determine a time window during which the device will be able to receive a command. ttl no long The time-to-live in milliseconds. A consumer of the message SHOULD discard the message if the sum of creation-time and ttl is greater than the current time (milliseconds since the Unix epoch). Protocol adapters MAY set additional attributes on the Pub/Sub message.\nNorthbound Operations The following operation can be used by Business Applications to receive telemetry data from Pub/Sub.\nSubscribe Telemetry Data To receive telemetry messages from Pub/Sub, a subscription must be created to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.telemetry where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant the client wants to retrieve telemetry data for. Only messages published to the topic after the subscription is created are available to subscriber clients like Business Applications. Please refer to the Pub/Sub Subscriber Documentation for more details.\nPreconditions\nThe topic projects/${google_project_id}/topics/${tenant_id}.telemetry exists. A subscription to that topic exists. The client is authorized to Pub/Sub. Message Format\nThe format of the messages containing the telemetry data is the same as for the Publish Telemetry Data operation.\n",
    "description": "",
    "tags": null,
    "title": "Telemetry API Specification for Google Pub/Sub",
    "uri": "/hono/docs/2.7/api/telemetry-pubsub/"
  },
  {
    "content": "The Event API is used by Protocol Adapters to send event messages downstream. Business Applications and other consumers use the API to receive messages published by devices belonging to a particular tenant.\nThe Event API is defined by means of Google Pub/Sub message exchanges, i.e. a client needs to connect to Hono and configure Hono for Google Pub/Sub messaging infrastructure in order to use it and invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use Pub/Sub when referring to Google Pub/Sub.\nThe Event API for Pub/Sub is an alternative to the Event API for Kafka for applications that want to consume events from Pub/Sub instead of an Apache Kafka™ broker.\nWarning Support for the Google Pub/Sub based Event API is considered experimental and may change without further notice.\nSouthbound Operations The following operation can be used by Protocol Adapters to publish event messages received from devices to consumers like Business Applications.\nPublish Event Data The protocol adapter writes messages to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.event where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant that the client wants to upload event messages for.\nPreconditions\nA Google Cloud Project is set up with the Pub/Sub API enabled. The ID of the Google Cloud Project is declared as mentioned in the Publisher Configuration. The client is authorized to write to the topic. The device for which the adapter wants to send event messages has been registered (see Device Registration API). Message Flow\nHono supports AT LEAST ONCE delivery of Event messages only.\nThe following sequence diagram illustrates the flow of messages involved in the MQTT Adapter publishing an event to the Pub/Sub API.\nPublish event flow Device 4711 publishes an event using MQTT QoS 1. MQTT Adapter transfers data to the Pub/Sub API. Pub/Sub API acknowledges reception of the message. MQTT Adapter acknowledges the reception of the message to the Device. When a Pub/Sub publisher raises an exception while sending an event message to Pub/Sub, the protocol adapter MUST NOT try to re-send such rejected messages but MUST indicate the failed transfer to the device if the transport protocol provides means to do so.\nMessage Format\nSee Telemetry API for Pub/Sub for definition of message format.\nNorthbound Operations The following operation can be used by Business Applications to receive event messages from Pub/Sub.\nSubscribe Events To receive event messages from Pub/Sub, a subscription must be created to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.event where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant the client wants to retrieve event messages for. Only messages published to the topic after the subscription is created are available to subscriber clients like Business Applications. Please refer to the Pub/Sub Subscriber Documentation for more details.\nPreconditions\nThe topic projects/${google_project_id}/topics/${tenant_id}.event exists. A subscription to that topic exists. The client is authorized to Pub/Sub. Message Format\nSee Telemetry API for Pub/Sub for the definition of the message format.\n",
    "description": "",
    "tags": null,
    "title": "Event API Specification for Google Pub/Sub",
    "uri": "/hono/docs/2.7/api/event-pubsub/"
  },
  {
    "content": "The Command \u0026 Control API of Eclipse Hono™ is used by Business Applications to send commands to connected devices.\nCommands can be used to trigger actions on devices. Examples include updating a configuration property, installing a software component or switching the state of an actuator.\nHono distinguishes two types of commands. The first type is one-way only. In this case the sender of the command does not expect the device to send back a message in response to the command. This type of command is referred to as a one-way command in the remainder of this page. One-way commands may be used to e.g. notify a device about a change of state.\nThe second type of commands expects a response to be sent back from the device as a result of processing the command. In this case the response contains a status code which indicates whether the command could be processed successfully. If so, the response may also include data representing the result of processing the command. This type of command is plainly referred to as a command because it represents the default case.\nThe Command \u0026 Control API is defined by means of Google Pub/Sub message exchanges, i.e. a client needs to connect to Hono and configure Hono for Google Pub/Sub messaging infrastructure in order to use it and invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use Pub/Sub when referring to Google Pub/Sub.\nThe Command \u0026 Control API for Pub/Sub is an alternative to the Command \u0026 Control API for Kafka for applications that want to use Pub/Sub instead of an Apache Kafka™ broker to send command messages to devices.\nWarning Support for the Google Pub/Sub based Command \u0026 Control API is considered experimental and may change without further notice.\nSend a One-Way Command Business Applications use this operation to send a command to a device for which they do not expect to receive a response from the device. For that, the Business Application connects to Pub/Sub and writes a message to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.command where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant that the client wants to send the command for.\nPreconditions\nA Google Cloud Project is set up with the Pub/Sub API enabled. The ID of the Google Cloud Project is declared as mentioned in the Publisher and Subscriber Configuration. The Business Application is authorized to write to the topic. The topic projects/${google_project_id}/topics/${tenant_id}.command exists. The subscription projects/${google_project_id}/subscriptions/${tenant_id}.command exists. Message Flow\nThe Business Application writes a command message to the topic projects/${google_project_id}/topics/${tenant_id}.command on Pub/Sub. Hono consumes the message through the subscription projects/${google_project_id}/subscriptions/${tenant_id}.command from Pub/Sub and forwards it to the device, provided that the target device is connected and is accepting commands. Message Format\nMetadata MUST be set as Pub/Sub attributes on a message. The following table provides an overview of the attributes the Business Application needs to set on a one-way command message.\nName Mandatory Type Description device_id yes string The identifier of the device that the command is targeted at. subject yes string The name of the command to be executed by the device. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. The command message MAY contain arbitrary payload, set as message value, to be sent to the device. The value of the message’s subject attribute may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nSend a (Request/Response) Command Business Applications use this operation to send a command to a device for which they expect the device to send back a response. For that, the Business Application connects to Pub/Sub and writes a message to the tenant-specific topic projects/${google_project_id}/topics/${tenant_id}.command where ${google_project_id} is the ID of the Google Cloud project and ${tenant_id} is the ID of the tenant that the client wants to send the command for.\nThe Business Application can consume the corresponding command response by creating a subscription from the projects/${google_project_id}/topics/${tenant_id}.command_response topic.\nIn contrast to a one-way command, a request/response command contains either a response-required or an ack-required attribute with value true and a correlation-id attribute, providing the identifier that is used to correlate a response message to the original request.\nDevices can vary in their ability to respond to commands (e.g. firmware limitations). The Business Application can tailor its expectations based on this:\nDevice Response Expected: For devices that can send a response, set response-required to true. This is the default behavior for sending request/response commands. The command is sent with the correlation-id to the device, which is then expected to send a corresponding command response.\nAcknowledgement Only: For devices lacking response capability, set ack-required to true. The command is sent without the correlation-id to the device, and the protocol adapter sends a positive acknowledgement as a command response on behalf of the device upon receiving a transport layer confirmation (e.g., MQTT PUBACK) from the device.\nWarning Setting both response-required and ack-required to true is invalid and will result in the command being rejected.\nPreconditions\nThe topics projects/${google_project_id}/topics/${tenant_id}.command and projects/${google_project_id}/topics/${tenant_id}.command_response exist The subscription projects/${google_project_id}/subscriptions/${tenant_id}.command to the topic projects/${google_project_id}/topics/${tenant_id}.command exists. A subscription to the topic projects/${google_project_id}/topics/${tenant_id}.command_response exists. The Business Application is authorized to write to the projects/${google_project_id}/topics/${tenant_id}.command topic and read from the subscriptions. Message Flow\nDevice sends response (response-required set to true):\nThe Business Application writes a command message with response-required set to true to the projects/${google_project_id}/topics/${tenant_id}.command topic on Pub/Sub. Hono consumes the message from Pub/Sub and forwards it to the device, provided that the target device is connected and is accepting commands. The device sends a command response message. Hono writes that message to the projects/${google_project_id}/topics/${tenant_id}.command_response topic on Pub/Sub. The Business Application consumes the command response message from an independently created subscription to the projects/${google_project_id}/topics/${tenant_id}.command_response topic. Protocol adapter sends response on behalf of device (ack-required set to true):\nThe Business Application writes a command message with ack-required set to true to the projects/${google_project_id}/topics/${tenant_id}.command topic on Pub/Sub. Hono consumes the message from Pub/Sub and forwards it to the device as a one-way command, provided that the target device is connected and is accepting commands. The device acknowledges reception of the command on the transport layer. Hono writes an acknowledgement message to the projects/${google_project_id}/topics/${tenant_id}.command_response topic on Pub/Sub. The Business Application consumes the command response message from an independently created subscription to the projects/${google_project_id}/topics/${tenant_id}.command_response topic. Command Message Format\nMetadata MUST be set as Pub/Sub attributes on a message. The following table provides an overview of the attributes the Business Application needs to set on a request/response command message.\nName Mandatory Type Description correlation-id yes string The identifier used to correlate a response message to the original request. It is used as the correlation-id attribute in the response. device_id yes string The identifier of the device that the command is targeted at. response-required no boolean true if the device is required to send a response for the command. response-required and ack-required MUST NOT both be set to true at the same time. ack-required no boolean true if the protocol adapter should send an acknowledgement response for the command on behalf of the device in case the command was successfully received by the device. This mechanism has some limitations which are described in the info field below. response-required and ack-required MUST NOT both be set to true at the same time. subject yes string The name of the command to be executed by the device. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers. delivery-failure-notification-metadata[*] no string Attributes with the delivery-failure-notification-metadata prefix are adopted for the error command response that is sent in case delivering the command to the device failed. In case of a successful command delivery, these attributes are ignored. The command message MAY contain arbitrary payload, set as message value, to be sent to the device. The value of the message’s subject attribute may provide a hint to the device regarding the format, encoding and semantics of the payload data.\nInfo The acknowledgement mechanism is based on the transport level acknowledgement of the different communication protocols and indicates that a command was received from the device. For MQTT devices this means they must subscribe on the command topic with a Quality of Service (QoS) level of 1. Since the HTTP protocol doesn’t support a transport level acknowledgement, acknowledgements are considered best-effort, indicating the message was sent, not necessarily received.\nCurrently, the acknowledgement mechanism only works with devices connected via the MQTT and HTTP protocol.\nAn application can determine the overall outcome of the operation by means of the response to the command. The response is either sent back by the device (response-required) or the adapter (ack-required), or in case the command could not be successfully forwarded to the device, an error command response message is sent by the Hono protocol adapter or Command Router component.\nResponse Message Format\nMetadata MUST be set as Pub/Sub attributes on a message. The following table provides an overview of the attributes set on a message sent in response to a command.\nName Mandatory Type Description correlation-id yes string MUST contain the value of the correlation-id attribute of the request message that this is the response for. creation-time yes long The instant in time (milliseconds since the Unix epoch) when the message has been created. device_id yes string The identifier of the device that sent the response. status yes integer MUST indicate the status of the execution. See table below for possible values. tenant_id yes string The identifier of the tenant that the device belongs to. content-type no string If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.\nIf the response is an error message sent by the Hono protocol adapter or Command Router component, the content type MUST be application/vnd.eclipse-hono-delivery-failure-notification+json. delivery-failure-notification-metadata[*] no string MUST be adopted from the command message attributes with the same names if the response is an error message sent by the Hono protocol adapter or Command Router component. The status attribute must contain an HTTP 1.1 response status code.\nThe command response message MAY contain arbitrary payload, set as message value, to be sent to the business application.\nResponse Message sent from Device\nIn a response from a device, the semantics of the status code ranges are as follows:\nCode Description 2xx The command has been processed successfully. 4xx The command could not be processed due to a client error, e.g. malformed message payload. 5xx The command could not be processed due to an internal problem at the device side. The semantics of the individual codes are specific to the device and command. For status codes indicating an error (codes in the 400 - 599 range) the message body MAY contain a detailed description of the error that occurred.\nResponse Message sent from Hono Component\nIf the command response is an acknowledgement of a command by the Hono protocol adapter, it has a status code of 202 and the content-type attribute is set to application/vnd.eclipse-hono-delivery-success-notification+json.\nIf the command response message represents an error message sent by the Hono protocol adapter or Command Router component, with the content-type attribute set to application/vnd.eclipse-hono-delivery-failure-notification+json, the possible status codes are:\nCode Description 4xx The command has not been delivered to or processed by the device because the command message does not contain all required information. Another reason may be that a message limit has been exceeded. 5xx The command has not been delivered to the device or can not be processed by the device due to reasons that are not the responsibility of the sender of the command. Possible reasons are:The device is (currently) not connected.In case the transport protocol supports acknowledgements: The device hasn’t sent an acknowledgement in time or has indicated that the message cannot be processed.There was an error forwarding the command to the device. The payload MUST contain a UTF-8 encoded string representation of a single JSON object with the following fields:\nName Mandatory Type Description error yes string The error message describing the cause for the command message delivery failure. ",
    "description": "",
    "tags": null,
    "title": "Command \u0026 Control API Specification for Google Pub/Sub",
    "uri": "/hono/docs/2.7/api/command-and-control-pubsub/"
  },
  {
    "content": "The Tenant API is used by Hono’s protocol adapters to retrieve information that affects all devices belonging to a particular tenant. A tenant is a logical entity, which groups together a set of devices. The information registered for a tenant is used for example to determine if devices belonging to the tenant are allowed to connect to a certain protocol adapter or if devices are required to authenticate.\nThis document describes the Tenant API’s operations and the payload data format used by them. Please refer to Multi Tenancy for details regarding the way Hono supports multiple tenants.\nThe Tenant API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nPreconditions for invoking the Tenant API Client has established an AMQP connection with the Tenant service. Client has established an AMQP link in role sender on the connection using target address tenant. This link is used by the client to send request messages to the Tenant service. Client has established an AMQP link in role receiver on the connection using source address tenant/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Tenant service. This link’s source address is also referred to as the reply-to address for the request messages. Client connecting to Tenant service Get Tenant Information Clients use this operation to retrieve information about a tenant.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Client retrieving tenant information.\nClient retrieving tenant information Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to get tenant information:\nName Mandatory Location AMQP Type Description correlation-id no properties message-id MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the client wants to receive response messages from. This address MUST be the same as the source address used for establishing the client’s receive link (see Preconditions). subject yes properties string MUST be set to get. The body of the request message MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON object.\nThe JSON object MUST contain exactly one of the following search criteria properties:\nName Mandatory JSON Type Description subject-dn no string The subject DN of the trusted certificate authority’s public key in the format defined by RFC 2253. tenant-id no string The identifier of the tenant to get. The following request payload may be used to look up the tenant with identifier ACME Corporation:\n{ \"tenant-id\": \"ACME Corporation\" } The following request payload may be used to look up the tenant for which a trusted certificate authority with subject DN O=ACME Corporation, CN=devices has been configured:\n{ \"subject-dn\": \"CN=devices,O=ACME Corporation\" } Response Message Format\nThe following table provides an overview of the properties contained in a response message to a get tenant information request:\nName Mandatory Location AMQP Type Description correlation-id yes properties message-id Contains the message-id (or the correlation-id, if specified) of the request message that this message is the response to. content-type no properties string MUST be set to application/json if the invocation of the operation was successful and the body of the response message contains payload as described below. status yes application-properties int Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined for each particular operation. cache_control no application-properties string Contains an RFC 2616 compliant cache directive. The directive contained in the property MUST be obeyed by clients that are caching responses. The response message’s status property may contain the following codes:\nCode Description 200 OK, The response message body contains the requested tenant information. 400 Bad Request, the request message did not contain all mandatory properties. 403 Forbidden, the client is not authorized to retrieve information for the given tenant. 404 Not Found, there is no tenant matching the given search criteria. For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message’s content-type property SHOULD be set accordingly.\nOtherwise the response message contains the information for the requested tenant as described in the following sections.\nTenant Information Format Tenant information is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.\nThe table below provides an overview of the standard members defined for the JSON response object:\nName Mandatory JSON Type Description adapters no array A list of configuration options valid for certain adapters only. The format of a configuration option is described here Adapter Configuration Format. NB If the element is provided then the list MUST NOT be empty. NB Only a single entry per type is allowed. If multiple entries for the same type are present it is handled as an error. NB If the element is omitted then all adapters are enabled in their default configuration. defaults no object Arbitrary default properties for devices belonging to the tenant. The properties can be used by protocol adapters to augment downstream messages with missing information, e.g. setting a default content type or time-to-live. enabled yes boolean If set to false the tenant is currently disabled. Protocol adapters MUST NOT allow devices of a disabled tenant to connect and MUST NOT accept data published by such devices. minimum-message-size no number The minimum message size in bytes. If it is set then the payload size of the telemetry, event and command messages are calculated in accordance with the configured value and then reported to the metrics. See Metrics for more details. resource-limits no object Any resource limits that should be enforced for the tenant, e.g. the maximum number of concurrent connections and the maximum data volume for a given period. Refer to Resource Limits Configuration Format for details. tenant-id yes string The ID of the tenant. tracing no object A set of options regarding the tracing of messages for the tenant. See Tracing Format for a definition of the content model of the object. trusted-ca no array The list of trusted certificate authorities to use for validating certificates presented by devices of the tenant for authentication purposes. See Trusted Certificate Authority Format for a definition of the content model of the objects contained in the array. NB If the element is provided then the list MUST NOT be empty. ext no object Arbitrary extension properties belonging to the tenant. See Extension properties Format for details. The JSON object MAY contain an arbitrary number of additional members with arbitrary names which can be of a scalar or a complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.\nExamples\nThe JSON structure below contains example information for tenant TEST_TENANT. Note that the structure contains some custom properties at both the root level (customer) as well as the adapter configuration level (deployment) and also defines a default TTL for downstream messages.\n{ \"tenant-id\": \"TEST_TENANT\", \"defaults\": { \"ttl\": 30 }, \"enabled\": true, \"customer\": \"ACME Inc.\", \"resource-limits\": { \"max-connections\": 100000, \"data-volume\": { \"max-bytes\": 2147483648, \"period\": { \"mode\": \"days\", \"no-of-days\": 30 }, \"effective-since\": \"2019-07-27T14:30:00Z\" } }, \"adapters\": [ { \"type\": \"hono-mqtt\", \"enabled\": true, \"device-authentication-required\": true }, { \"type\": \"hono-http\", \"enabled\": true, \"device-authentication-required\": true, \"deployment\": { \"maxInstances\": 4 } } ] } Tracing Format The table below provides an overview of the members defined for the tracing JSON object:\nName Mandatory Type Default Value Description sampling-mode no string default Defines in how far OpenTracing spans created when processing messages for this tenant shall be recorded (sampled) by the tracing system. The value default lets the default sampling mechanism be used. The value all marks the spans related to this tenant so that they should all be sampled. The value none marks the spans as not to be sampled. The mode defined here may be overridden for a particular auth-id by means of the sampling-mode-per-auth-id property. sampling-mode-per-auth-id no object Defines in how far OpenTracing spans created when processing messages for this tenant and a particular auth-id shall be recorded (sampled) by the tracing system. The child properties have the auth-id as name. A child property value of default lets the default sampling mechanism be used. The child property value all marks the spans related to this tenant and the auth-id so that they should all be sampled. The child property value none marks the spans as not to be sampled. The mode defined for a particular auth-id has precedence over the value defined by the sampling-mode property. Trusted CA Format The table below provides an overview of the members of a JSON object representing a trusted CA:\nName Mandatory Type Default Value Description subject-dn yes string - The subject DN of the trusted root certificate in the format defined by RFC 2253. public-key yes string - The Base64 encoded binary DER encoding of the trusted root certificate’s public key. algorithm no string RSA The name of the public key algorithm. Supported values are RSA and EC. auto-provisioning-enabled no boolean false If true, protocol adapters MAY request auto-provisioning of devices that authenticate with a client certificate issued by this CA. Otherwise, protocol adapters MUST NOT request auto-provisioning. Examples\nBelow is an example payload for a response to a get request for tenant TEST_TENANT. The tenant is configured with two trusted certificate authorities, each using a different public key algorithm. Only one of them is configured to be used for auto-provisioning.\n{ \"tenant-id\" : \"TEST_TENANT\", \"enabled\" : true, \"trusted-ca\": [{ \"subject-dn\": \"CN=ca,OU=Hono,O=Eclipse\", \"public-key\": \"PublicKey==\", \"auto-provisioning-enabled\": false, \"algorithm\": \"RSA\" }, { \"subject-dn\": \"CN=ca,OU=Hono,O=ACME Inc.\", \"public-key\": \"ECKey==\", \"auto-provisioning-enabled\": true, \"algorithm\": \"EC\" }] } Adapter Configuration Format The table below contains the properties which are used to configure a Hono protocol adapter:\nName Mandatory JSON Type Default Value Description type yes string - The type of the adapter which this configuration belongs to. enabled no boolean false If false, the tenant is not allowed to receive/send data utilizing the given type of adapter. device-authentication-required no boolean true If false, devices are not required to authenticate with an adapter of the given type before sending/receiving data. Protocol adapters SHOULD use the configuration properties set for a tenant when interacting with devices of that tenant, e.g. in order to make authorization decisions etc.\nThe JSON object MAY contain an arbitrary number of additional members with arbitrary names of either scalar or complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.\nResource Limits Configuration Format The table below contains the properties which are used to configure a tenant’s resource limits:\nName Mandatory JSON Type Default Value Description connection-duration no object - The maximum connection duration allowed for the given tenant. Refer to Connection Duration Configuration Format for details. data-volume no object - The maximum data volume allowed for the given tenant. Refer to Data Volume Configuration Format for details. max-connections no number -1 The maximum number of concurrent connections allowed from devices of this tenant. The default value -1 indicates that no limit is set. max-ttl no number -1 The maximum time-to-live (in seconds) to use for events published by devices of this tenant. Note that this property contains the TTL in seconds whereas the AMQP 1.0 specification defines a message’s ttl header to use milliseconds. max-ttl-command-response no number -1 The maximum time-to-live (in seconds) to use for command response messages published by devices of this tenant. Note that this property contains the TTL in seconds whereas the AMQP 1.0 specification defines a message’s ttl header to use milliseconds. max-ttl-telemetry-qos0 no number -1 The maximum time-to-live (in seconds) to use for telemetry messages published by devices of this tenant using QoS 0. Note that this property contains the TTL in seconds whereas the AMQP 1.0 specification defines a message’s ttl header to use milliseconds. max-ttl-telemetry-qos1 no number -1 The maximum time-to-live (in seconds) to use for telemetry messages published by devices of this tenant using QoS 1. Note that this property contains the TTL in seconds whereas the AMQP 1.0 specification defines a message’s ttl header to use milliseconds. Protocol adapters SHOULD use the max-connections property to determine if a device’s connection request should be accepted or rejected.\nProtocol adapters SHOULD use the max-ttl property to determine the effective time-to-live for event messages published by devices as follows:\nSet effective ttl to -1 (unlimited). If a max-ttl value greater than effective ttl is set for the tenant, use that value as the new effective ttl. If the event published by the device contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl. does not contain a ttl header but a default property with name ttl is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds). Protocol adapters SHOULD use the max-ttl-telemetry-qos0 and max-ttl-telemetry-qos1 properties to determine the effective time-to-live for telemetry messages published by devices with QoS 0 or QoS 1 respectively as follows:\nSet effective ttl to -1 (unlimited). If a max-ttl-telemetry-qos0 value greater than effective ttl is set for the tenant, use that value as the new effective ttl. If the message published by the device contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl. does not contain a ttl header but a default property with name ttl-telemetry-qos0 is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds). Protocol adapters SHOULD use the max-ttl-command-response property to determine the effective time-to-live for command response messages published by devices as follows:\nSet effective ttl to -1 (unlimited). If a max-ttl-command-response value greater than effective ttl is set for the tenant, use that value as the new effective ttl. If the message published by the device contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl. does not contain a ttl header but a default property with name ttl-command-response is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds). The JSON object MAY contain an arbitrary number of additional members with arbitrary names of either scalar or complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.\nConnection Duration Configuration Format The table below contains the properties which are used to configure a tenant’s connection duration limit:\nName Mandatory JSON Type Default Value Description effective-since yes string - The point in time at which the current settings became effective, i.e. the start of the first accounting period based on these settings. The value MUST be an ISO 8601 compliant combined date and time representation in extended format. max-minutes no number -1 The maximum connection duration in minutes allowed for the tenant for each accounting period. MUST be an integer. Minus one indicates that no limit is set. period no object - The mode and length of an accounting period, i.e. the resource usage is calculated based on the defined number of days or on a monthly basis. For more information, please refer to the resource limits period. Protocol adapters that maintain connection state SHOULD use this information to determine if a connection request from a device should be accepted or not. For more information, please refer to the connection duration limit concept.\nData Volume Configuration Format The table below contains the properties which are used to configure a tenant’s data volume limit:\nName Mandatory JSON Type Default Value Description effective-since yes string - The point in time at which the current settings became effective, i.e. the start of the first accounting period based on these settings. The value MUST be an ISO 8601 compliant combined date and time representation in extended format. max-bytes no number -1 The maximum number of bytes allowed for the tenant for each accounting period. MUST be an integer. A negative value indicates that no limit is set. period no object - The mode and length of an accounting period, i.e. the data usage can limited based on the defined number of days or on a monthly basis. For more information, please refer to the resource limits period. Protocol adapters SHOULD use this information to determine if a message originating from or destined to a device should be accepted for processing.\nResource Limits Period Configuration Format The table below contains the properties that are used to configure a tenant’s resource limits period:\nName Mandatory JSON Type Default Value Description mode yes string - The mode of the resource usage calculation. The default implementation supports two modes namely days and monthly. no-of-days no number - When the mode is set as days, then this value represents the length of an accounting period , i.e. the number of days over which the resource usage is to be limited. MUST be a positive integer. Extension properties Format The table below contains the extension properties that are used for addition configuration:\nName Mandatory JSON Type Default Value Description invalidate-cache-on-update no boolean false If set to true, the clients must purge the cached tenant’s entity when they receive change notification for update operation. Delivery States used by the Tenant API A Tenant service implementation uses the following AMQP message delivery states when receiving request messages from clients:\nDelivery State Description ACCEPTED Indicates that the request message has been received and accepted for processing. REJECTED Indicates that the request message has been received but cannot be processed. The disposition frame’s error field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties and payload in this case. ",
    "description": "",
    "tags": null,
    "title": "Tenant API Specification",
    "uri": "/hono/docs/2.7/api/tenant/"
  },
  {
    "content": "Protocol Adapters use the Command Router API to supply information with which a Command Router service component can route command \u0026 control messages to the protocol adapters that the target devices are connected to.\nThe Command Router API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to the service component using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nPreconditions for invoking the Command Router API Client has established an AMQP connection with the Command Router service. Client has established an AMQP link in role sender on the connection using target address cmd_router/${tenant_id}. This link is used by the client to send request messages to the Command Router service. Client has established an AMQP link in role receiver on the connection using source address cmd_router/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Command Router service. This link’s source address is also referred to as the reply-to address for the request messages. Client connecting to Command Router service Register command consumer for device Clients use this command to register a protocol adapter instance as the consumer of command \u0026 control messages for a device or gateway currently connected to that particular adapter instance.\nClients can provide an optional send_event parameter with value true to trigger a Time until Disconnect Notification with ttd value -1 indicating the device is ready to receive commands.\nClients can provide an optional lifespan parameter to make the registration entry expire after the given number of seconds. Note that implementations of this API have to support this feature, otherwise the Command Router service component might fail to correctly route command messages.\nThis API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient registers the command consumer for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to register the command consumer for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to register-cmd-consumer. adapter_instance_id yes application-properties string The identifier of the protocol adapter instance that currently handles commands for the device or gateway identified by the device_id property. device_id yes application-properties string MUST contain the ID of the device that is subject to the operation. send_event no application-properties boolean If set to true, a Time until Disconnect Notification with ttd value -1 should be sent indicating the device is ready to receive commands. lifespan no application-properties int The lifespan of the mapping entry in seconds. After that period, the registration entry shall be treated as non-existent by the Command Router service component. A negative value, as well as an omitted property, is interpreted as an unlimited lifespan. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a register command consumer for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the command consumer registration entry for the device has been created or updated. 400 Bad Request, the command consumer registration entry for the device has not been created or updated due to invalid or missing data in the request. Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nUnregister command consumer for device Clients use this command to unregister a command consumer for the given device. The consumer registration entry to be removed is identified by the provided protocol adapter instance handling command \u0026 control messages for a given device. The registration entry for the device is only removed, if the adapter instance identifier of the current registration entry matches the one given in the request.\nClients can provide an optional send_event parameter with value true to trigger a Time until Disconnect Notification with ttd value 0 indicating the device is not ready to receive commands.\nThis API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient unregisters the command consumer for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to remove the consumer registration entry for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to unregister-cmd-consumer. adapter_instance_id yes application-properties string The identifier of the protocol adapter instance to remove the registration entry for. Only if this adapter instance is currently associated with the device or gateway identified by the device_id property, the registration entry will be removed. device_id yes application-properties string MUST contain the ID of the device that is subject to the operation. send_event no application-properties boolean If set to true, a Time until Disconnect Notification with ttd value 0 should be sent indicating the device is not ready to receive commands. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a unregister command consumer for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the command consumer registration entry for the device has been removed. 400 Bad Request, the request message does not contain all required properties. 412 Precondition failed, the registration entry for the device has not been removed because there is no command consumer registration entry matching the adapter instance assigned to the device. This may happen if the mapping entry has already been removed or its lifespan has elapsed. The entry could also have been updated with a different adapter instance identifier before, which could for example mean the device lost its connection to the protocol adapter and has reconnected to a different adapter instance. The original adapter instance trying to remove the mapping entry at some point after that will result in a 412 error response because the instance identifier doesn’t match. Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nSet last known Gateway for Device Clients use this command to set the gateway that last acted on behalf of a given device.\nThere are two variants of this command, one providing a single gateway and device identifier combination via request application-properties and one providing a map of multiple such combinations in the request payload.\nAs this operation is invoked frequently by Hono’s components, implementors may choose to keep this information in memory. This API doesn’t mandate checks on the validity of the given device or gateway IDs in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient sets the last known gateway for a device Request Message Format - Setting single entry\nThe following table provides an overview of the properties a client needs to set on a message to set the last known gateway for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to set-last-gw. device_id yes application-properties string MUST contain the ID of the device that is subject to the operation. gateway_id yes application-properties string The identifier of the gateway that last acted on behalf of the device identified by the device_id property. For a device that connects to the adapter directly instead of through a gateway, the value of this property MUST be the same as the value of the device_id application property. The body of the message SHOULD be empty and will be ignored if it is not.\nRequest Message Format - Setting multiple entries\nThe following table provides an overview of the properties a client needs to set on a message to set multiple last known gateway and device pairs in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to set-last-gw. The body of the request MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON object. The device identifiers are to be used as fields, the corresponding gateway identifiers as string values. Note that the number of entries supported in the object may be limited by the maximum message size negotiated between the service and the client. In such a case, a client may use multiple consecutive requests to overcome this limitation.\nExample payload for setting gateway-1 as last known gateway for the devices device-1 and device-2.\n{ \"device-1\": \"gateway-1\", \"device-2\": \"gateway-1\" } Response Message Format\nA response to a set last known gateway for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the update of the last known gateway(s) for the device(s) was successful. 400 Bad Request, the update of the last known gateway(s) for the device(s) failed due to invalid or missing data in the request. Implementors of this API may return a 404 status code for the single entry operation in order to indicate that no device and/or gateway with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nEnable Command Routing A Protocol Adapter uses this operation to inform the Command Router service about the tenants that the devices belong to that are connected to the adapter and which have subscribed to commands.\nDuring normal operation, the Command Router is able to keep track of these tenants implicitly as part of the information provided in invocations of the register command consumer operation. Depending on the service’s implementation, this information might be lost after an unexpected restart. Protocol adapters will perceive such a case by means of a loss of their AMQP connection to the service. Once the connection has been re-established, an adapter can then use this operation to help the Command Router service recover and re-establish the downstream network links which are required to receive and forward commands.\nMessage Flow\nClient submits tenant IDs to enable command routing for Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to enable command routing in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to enable-command-routing. The body of the request MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON array containing tenant identifiers. Note that the number of tenant identifiers supported in the array may be limited by the maximum message size negotiated between the service and the client. In such a case, a client may use multiple consecutive requests to overcome this limitation.\nThe following request payload may be used to re-enable command routing of tenants one, two and three:\n[ \"one\", \"two\", \"three\" ] Response Message Format\nA response to an enable command routing request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the tenant identifiers have been accepted for processing. Note that this status code does not necessarily mean that command routing has already been enabled (again) for the given tenant identifiers. Implementors may also choose to accept the tenant identifiers and then (asynchronously) start to process them afterwards. In such a case, implementors are advised to implement adequate re-try logic for enabling command routing for each tenant identifier. 400 Bad Request, the body does not contain a valid JSON array of strings. For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nStandard Message Properties Due to the nature of the request/response message pattern of the operations of the Command Router API, there are some standard properties shared by all of the request and response messages exchanged as part of the operations.\nStandard Request Properties The following table provides an overview of the properties shared by all request messages regardless of the particular operation being invoked.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to the value defined by the particular operation being invoked. correlation-id no properties message-id MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the client wants to received response messages from. This address MUST be the same as the source address used for establishing the client’s receive link (see Preconditions). Standard Response Properties The following table provides an overview of the properties shared by all response messages regardless of the particular operation being invoked.\nName Mandatory Location AMQP Type Description correlation-id yes properties message-id Contains the message-id (or the correlation-id, if specified) of the request message that this message is the response to. status yes application-properties int Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined for each particular operation. cache_control no application-properties string Contains an RFC 2616 compliant cache directive. The directive contained in the property MUST be obeyed by clients that are caching responses. Delivery States Hono uses the following AMQP message delivery states when receiving request messages from clients:\nDelivery State Description ACCEPTED Indicates that the request message has been received and accepted for processing. REJECTED Indicates that Hono has received the request but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case. ",
    "description": "",
    "tags": null,
    "title": "Command Router API Specification",
    "uri": "/hono/docs/2.7/api/command-router/"
  },
  {
    "content": "The Device Registration API is used by Hono’s protocol adapters to get information about devices connecting to the adapters.\nThe Device Registration API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nPreconditions for invoking the Device Registration API Client has established an AMQP connection with the Device Registration service. Client has established an AMQP link in role sender on the connection using target address registration/${tenant_id}. This link is used by the client to send request messages to the Device Registration service. Client has established an AMQP link in role receiver on the connection using source address registration/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Device Registration service. This link’s source address is also referred to as the reply-to address for the request messages. Client connecting to Device Registration service Assert Device Registration Clients use this command to verify that a device is registered for a particular tenant and is enabled.\nMessage Flow\nThe following sequence diagram illustrates the flow of messages involved in a Client asserting a device’s registration status.\nClient asserting a device's registration status Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to assert a device’s registration status:\nName Mandatory Location AMQP Type Description correlation-id no properties message-id MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. device_id yes application-properties string MUST contain the ID of the device that is subject to the operation. gateway_id no application-properties string The identifier of the gateway that wants to get an assertion on behalf of another device (given in the device_id property).\nAn implementation SHOULD verify that the gateway exists, is enabled and is authorized to get an assertion for, and thus send data on behalf of, the device. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the client wants to received response messages from. This address MUST be the same as the source address used for establishing the client’s receive link (see Preconditions). subject yes properties string MUST be set to assert. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nThe following table provides an overview of the properties contained in a response message to an assert request:\nName Mandatory Location AMQP Type Description correlation-id yes properties message-id Contains the message-id (or the correlation-id, if specified) of the request message that this message is the response to. content-type no properties string MUST be set to application/json if the invocation of the operation was successful and the body of the response message contains payload as described below. status yes application-properties int Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined below. cache_control no application-properties string Contains an RFC 2616 compliant cache directive. The directive contained in the property MUST be obeyed by clients that are caching responses. In case of a successful invocation of the operation, the body of the response message consists of a single Data section containing a UTF-8 encoded string representation of a single JSON object having the following properties:\nName Mandatory JSON Type Description device-id yes string The ID of the device that is subject of the assertion. via no array The IDs (JSON strings) of gateways which may act on behalf of the device. This property MUST be set if any gateways are registered for the device. If the assertion request contained a gateway_id property and the response’s status property has value 200 (indicating a successful assertion) then the array MUST at least contain the gateway ID from the request. defaults no object Default values to be used by protocol adapters for augmenting messages from devices with missing information like a content type. It is up to the discretion of a protocol adapter if and how to use the given default values when processing messages published by the device. mapper no string The name of a service that can be used to transform messages uploaded by the device before they are forwarded to downstream consumers. The client needs to map this name to the particular service to invoke. Below is an example for a payload of a response to an assert request for device 4711 which also includes a default content-type and a mapper service:\n{ \"device-id\": \"4711\", \"via\": [\"4712\"], \"defaults\": { \"content-type\": \"application/vnd.acme+json\" }, \"mapper\": \"my-payload-transformation\" } The response message’s status property may contain the following codes:\nCode Description 200 OK, the device is registered for the given tenant and is enabled. The response message body contains the asserted device’s registration status. 400 Bad Request, the request message did not contain all mandatory properties. 403 Forbidden, the gateway with the given gateway id either does not exist, is not enabled or is not authorized to get an assertion for the device with the given device id. 404 Not Found, there is no device registered with the given device id within the given tenant id or the device is not enabled. For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message’s content-type property SHOULD be set accordingly.\nDelivery States The Device Registration service uses the following AMQP message delivery states when receiving request messages from clients:\nDelivery State Description ACCEPTED Indicates that the request message has been received and accepted for processing. REJECTED Indicates that the request message has been received but cannot be processed. The disposition frame’s error field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case. ",
    "description": "",
    "tags": null,
    "title": "Device Registration API Specification",
    "uri": "/hono/docs/2.7/api/device-registration/"
  },
  {
    "content": "The Credentials API is used by Protocol Adapters to retrieve credentials used to authenticate Devices connecting to the adapter. In particular, the API supports to look up shared secrets which are often used by IoT devices by means of username/password based authentication schemes.\nCredentials are of a certain type which indicates which authentication mechanism the credentials can be used with. Each set of credentials also contains an authentication identity which is the identity claimed by the device during authentication. This authentication identity is usually different from the device-id the device has been registered under. A device may have multiple sets of credentials, using arbitrary authentication identities.\nThe Credentials API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nPreconditions for invoking the Credentials API Client has established an AMQP connection with the Credentials service. Client has established an AMQP link in role sender on the connection using target address credentials/${tenant_id}. This link is used by the client to send commands to the Credentials service. Client has established an AMQP link in role receiver on the connection using source address credentials/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Credentials service. This link’s source address is also referred to as the reply-to address for the request messages. Client connecting to Credentials service Get Credentials Protocol adapters use this command to look up credentials of a particular type for a device identity.\nMessage Flow\nClient looking up credentials for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on an get credentials message.\nName Mandatory Location AMQP Type Description correlation-id no properties message-id MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the client wants to receive response messages from. This address MUST be the same as the source address used for establishing the client’s receive link (see Preconditions). subject yes properties string MUST contain the value get. The body of the request MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON object having the following members:\nName Mandatory JSON Type Description type yes string The type of credentials to look up. Potential values include (but are not limited to) psk, x509-cert, hashed-password etc. auth-id yes string The authentication identifier to look up credentials for. client-certificate no string The client certificate the device authenticated with. If present, it MUST be the DER encoding of the (validated) X.509 client certificate as a Base64 encoded byte array and its subject DN MUST match the auth-id. The client-certificate property MAY be used by the service implementation for auto-provisioning of devices. To do so, the device registry needs to create credentials (and registration data) for the device if they do not already exist.\nAdditionally, the body MAY contain arbitrary properties that service implementations can use to determine a device’s identity.\nThe following request payload may be used to look up the hashed password for a device with the authentication identifier sensor1:\n{ \"type\": \"hashed-password\", \"auth-id\": \"sensor1\" } The following request payload may be used to look up or create x509-cert credentials for a device with the authentication identifier CN=device-1,O=ACME Corporation:\n{ \"type\": \"x509-cert\", \"auth-id\": \"CN=device-1,O=ACME Corporation\", \"client-certificate\": \"DeviceCert==\" } Response Message Format\nA response to a get credentials request contains the following properties:\nName Mandatory Location AMQP Type Description correlation-id yes properties message-id Contains the message-id (or the correlation-id, if specified) of the request message that this message is the response to. content-type no properties string MUST be set to application/json if the invocation of the operation was successful and the body of the response message contains payload as described below. status yes application-properties int Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined below. cache_control no application-properties string Contains an RFC 2616 compliant cache directive. The directive contained in the property MUST be obeyed by clients that are caching responses. The response message payload MUST contain credential information as defined in Credentials Format if the status is 200 or 201.\nThe response message’s status property may contain the following codes:\nCode Description 200 OK, the payload contains the credentials for the authentication identifier. 201 Created, the payload contains the newly created credentials for the authentication identifier. 400 Bad Request, the request message did not contain all mandatory properties or the subject DN of the certificate does not match the authentication identifier. 404 Not Found, there are no credentials registered matching the criteria. For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message’s content-type property SHOULD be set accordingly.\nDelivery States The Credentials service uses the following AMQP message delivery states when receiving request messages from clients:\nDelivery State Description ACCEPTED Indicates that the request message has been received and accepted for processing. REJECTED Indicates that the request message has been received but cannot be processed. The disposition frame’s error field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case. Credentials Format Credential data is carried in the body of an AMQP message as part of a single Data section. The message’s content-type property must be set to application/json.\nThe credential data is contained in the Data section as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.\nThe table below provides an overview of the standard members defined for the JSON object:\nName Mandatory JSON Type Default Value Description device-id yes string The ID of the device to which the credentials belong. type yes string The credential type name. The value may be arbitrarily chosen by clients but SHOULD reflect the particular type of authentication mechanism the credentials are to be used with. Possible values include (but are not limited to) psk, x509-cert, hashed-password etc. auth-id yes string The identity that the device should be authenticated as. enabled no boolean true If set to false the credentials are not supposed to be used to authenticate devices any longer. This may e.g. be used to disable a particular mechanism for authenticating the device. NB It is the responsibility of the protocol adapter to make use of this information. secrets yes array A list of secrets scoped to a particular time period. See Secrets Format for details. NB This array must contain at least one element - an empty array is considered an error. For each set of credentials the combination of auth-id and type MUST be unique within a tenant.\nThe device registry may choose to not return information which is not suitable for authentication a device. This includes for example the enabled property. If set to false, then the device registry may choose to treat this request as if no credentials would be found. For secrets for example, this could mean that the device registry does not return secrets which are not valid at the current point in time.\nInfo Care needs to be taken that the value for the authentication identifier is compliant with the authentication mechanism(s) it is supposed to be used with. For example, when using standard HTTP Basic authentication, the username part of the Basic Authorization header value (which corresponds to the auth-id) MUST not contain any colon (:) characters, because the colon character is used as the separator between username and password. Similar constraints may exist for other authentication mechanisms, so the authentication identifier needs to be chosen with the anticipated mechanism(s) being used in mind. Otherwise, devices may fail to authenticate with protocol adapters, even if the credentials provided by the device match the credentials registered for the device. In general, using only characters from the [a-zA-Z0-9_-] range for the authentication identifier should be compatible with most mechanisms.\nSecrets Format Each set of credentials may contain arbitrary secrets scoped to a particular validity period during which the secrets may be used for authenticating a device. The validity periods MAY overlap in order to support the process of changing a secret on a device that itself doesn’t support the definition of multiple secrets for gapless authentication across adjacent validity periods.\nThe table below contains the properties used to define the validity period of a single secret:\nName Mandatory JSON Type Default Value Description not-before no string null The point in time from which on the secret may be used to authenticate devices. If not null, the value MUST be an ISO 8601 compliant combined date and time representation in extended format. NB It is up to the discretion of the protocol adapter to make use of this information. not-after no string null The point in time until which the secret may be used to authenticate devices. If not null, the value MUST be an ISO 8601 compliant combined date and time representation in extended format. NB It is up to the discretion of the protocol adapter to make use of this information. Examples Below is an example for a payload containing a hashed password for device 4711 with auth-id sensor1 using SHA512 as the hashing function with a 4 byte salt (Base64 encoding of 0x32AEF017). Note that the payload does not contain a not-before property, thus it may be used immediately up until X-mas eve 2017.\n{ \"device-id\": \"4711\", \"type\": \"hashed-password\", \"auth-id\": \"sensor1\", \"enabled\": true, \"secrets\": [{ \"not-after\": \"2017-12-24T19:00:00+0100\", \"pwd-hash\": \"AQIDBAUGBwg=\", \"salt\": \"Mq7wFw==\", \"hash-function\": \"sha-512\" }] } The next example contains two pre-shared keys with overlapping validity periods for device myDevice with PSK identity little-sensor2.\n{ \"device-id\": \"myDevice\", \"type\": \"psk\", \"auth-id\": \"little-sensor2\", \"enabled\": true, \"secrets\": [{ \"not-after\": \"2017-07-01T00:00:00+0100\", \"key\": \"cGFzc3dvcmRfb2xk\" },{ \"not-before\": \"2017-06-29T00:00:00+0100\", \"key\": \"cGFzc3dvcmRfbmV3\" }] } Credential Verification Protocol Adapters are responsible for authenticating devices when they connect. The Credentials API provides the Get Credentials operation to support Protocol Adapters in doing so as illustrated below:\nThe following sequence diagram illustrates the flow of messages involved in a Protocol Adapter authenticating a device. This is shown for the MQTT Protocol Adapter as example how a device authenticates with a username and a hashed-password. The mechanism can be transferred to other protocols in a similar manner.\nMQTT Adapter authenticates device using the Credentials service Protocol adapters MUST comply with the following rules when verifying credentials presented by a device:\nCredentials that have their enabled property set to false MUST NOT be used for authentication.\nAdapters MUST only consider secrets for authentication which\nhave their not-before property set to either null or the current or a past point in time and have their not-after property set to either null or the current or a future point in time. Standard Credential Types The following sections define some standard credential types and their properties. Applications are encouraged to make use of these types. However, the types are not enforced anywhere in Hono and clients may of course add application specific properties to the credential types.\nCommon Properties All credential types used with Hono MUST contain device-id, type, auth-id, enabled and secrets properties as defined in Credentials Format.\nHashed Password A credential type for storing a (hashed) password for a device.\nExample:\n{ \"device-id\": \"4711\", \"type\": \"hashed-password\", \"auth-id\": \"sensor1\", \"secrets\": [{ \"pwd-hash\": \"AQIDBAUGBwg=\", \"salt\": \"Mq7wFw==\", \"hash-function\": \"sha-512\" }] } Name Mandatory JSON Type Default Description type yes string The credential type name, always hashed-password. auth-id yes string The identity that the device should be authenticated as. pwd-hash yes string The password hash (see table below for details). salt no string The Base64 encoding of the salt used in the password hash (see table below for details). hash-function no string sha-256 The name of the hash function used to create the password hash. The hash functions supported by Hono are described in the table below. Tip It is strongly recommended to use salted password hashes only. Furthermore, the salt should be unique per user and password, so no lookup table or rainbow table attacks can be used to crack the salt-hashed password. Whenever a password is updated for a user, the salt should change as well.\nNote The example above does not contain any of the not-before, not-after and enabled properties, thus the credentials can be used at any time according to the rules defined in Credential Verification.\nThe table below describes the hash functions supported by Hono and how they map to the secret structure.\nName Salt Usage Salt Location Password Hash Format sha-256 optional salt field The Base64 encoding of the bytes resulting from applying the sha-256 hash function to the byte array consisting of the salt bytes (if a salt is used) and the UTF-8 encoding of the clear text password. sha-512 optional salt field The Base64 encoding of the bytes resulting from applying the sha-512 hash function to the byte array consisting of the salt bytes (if a salt is used) and the UTF-8 encoding of the clear text password. bcrypt mandatory pwd-hash value The output of applying the Bcrypt hash function to the clear text password. The salt is contained in the password hash.\nNB Hono (currently) uses Spring Security for matching clear text passwords against Bcrypt hashes. However, this library only supports hashes containing the $2a$ prefix (see https://github.com/fpirsch/twin-bcrypt#about-prefixes) so Hono will fail to verify any passwords for which the corresponding Bcrypt hashes returned by the Credentials service contain e.g. the $2y$ prefix. Pre-Shared Key A credential type for storing a Pre-shared Key as used in (D)TLS handshakes.\nExample:\n{ \"device-id\": \"4711\", \"type\": \"psk\", \"auth-id\": \"little-sensor2\", \"secrets\": [{ \"key\": \"AQIDBAUGBwg=\" }] } Name Mandatory JSON Type Description type yes string The credential type name, always psk. auth-id yes string The PSK identity. key yes string The Base64 encoded bytes representing the shared (secret) key. Note The example above does not contain any of the not-before, not-after and enabled properties, thus the credentials can be used at any time according to the rules defined in Credential Verification.\nX.509 Certificate A credential type for storing the RFC 2253 formatted subject DN of a client certificate that is used to authenticate the device as part of a (D)TLS handshake.\nExample:\n{ \"device-id\": \"4711\", \"type\": \"x509-cert\", \"auth-id\": \"CN=device-1,O=ACME Corporation\", \"secrets\": [{}] } Name Mandatory JSON Type Description type yes string The credential type name, always x509-cert. auth-id yes string The subject DN of the client certificate in the format defined by RFC 2253. Note The example above does not contain any of the not-before, not-after and enabled properties. The not-before and not-after properties should be omitted if the validity period is the same as the period indicated by the client certificate’s corresponding properties. It is still necessary to provide a (empty) JSON object in the secrets array, though.\nRaw Public Key A credentials type for storing a public key as used in the JSON Web Token based Authentication to authenticate a device.\nExample with public key:\n{ \"device-id\": \"4711\", \"type\": \"rpk\", \"auth-id\": \"sensor1\", \"secrets\": [ { \"key\": \"MIIBIjANBgkqhki...yn7qGrzgQIDAQAB\" } ] } Example with X.509 certificate:\n{ \"device-id\": \"4711\", \"type\": \"rpk\", \"auth-id\": \"sensor1\", \"secrets\": [ { \"cert\": \"MIIDezCCAmOgAwI...GCfMrYD6dnpbg==\" } ] } Name Mandatory JSON Type Description type yes string The credential type name, always rpk. auth-id yes string The identity that the device should be authenticated as. key or cert yes string The Base64 encoded binary DER encoding of the public key (key) or X.509 certificate (cert). In case a certificate is provided the public key will be extracted from it and the certificate discarded. Note The example above does not contain any of the not-before, not-after and enabled properties, thus the credentials can be used at any time according to the rules defined in Credential Verification.\n",
    "description": "",
    "tags": null,
    "title": "Credentials API Specification",
    "uri": "/hono/docs/2.7/api/credentials/"
  },
  {
    "content": "The Authentication API is used to retrieve a token asserting a subject’s identity and granted authorities. Other service implementations use such a token to make authorization decisions on a client’s request to read or write from/to a resource or to invoke a certain operation.\nThe Authentication API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to an Authentication service using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nNote that a component implementing this API will most likely need to also provide means to add, alter or remove identities and authorities as well. However, Hono itself does not require this kind of functionality, thus this kind of functionality is considered out of scope of this API.\nIn a real world environment there will often already be an identity management system in place. In such cases it can make sense to just implement a facade exposing the Authentication API operations and mapping them to the underlying existing system’s functionality.\nGet Token Clients use this operation to\nverify a set of credentials and retrieve a token asserting the authenticated subject’s identity and granted authorities. Message Flow\nThe following sequence diagram illustrates the flow of messages involved in a Client retrieving a token.\nGet Token message flow The Client and Authentication service have agreed to use the SASL PLAIN mechanism for authenticating the client. The Client therefore sends the credentials of the identity it wants to retrieve a token for. The Authentication service successfully verifies the credentials and establishes the authorization ID. The Authentication service completes the SASL exchange with a successful outcome (SASL OK). The Client continues by opening an AMQP connection with the Authentication service. The Authentication service creates a token asserting the authorization ID and authorities established during the SASL exchange and associates it with the connection. The Client opens a receiving link using source address cbs. The Authentication service opens the link and sends the token associated with the connection to the Client. The Client closes the connection. Token Message Format\nOn successful establishment of the receiving link with the client as described above, the server sends a message to the client containing a token asserting the identity and authorities of the client that has been authenticated as part of establishing the underlying AMQP connection.\nThe following table provides an overview of the properties of the message sent to the client.\nName Location Type Value type application-properties string amqp:jwt The message’s body consists of a single AMQP 1.0 AmqpValue section which contains the UTF-8 representation of a JSON Web Token as defined in Token Format.\nToken Format The token returned by the get Token operation is a cryptographically signed JSON Web Token as defined by RFC 7519.\nThe token contains the following mandatory claims:\nName Type Value sub RFC 7519, Section 4.1.2 The authorization ID of the authenticated client. This represents the asserted identity. exp RFC 7519, Section 4.1.4 The point in time after which the claims contained in this token must be considered no longer valid. Clients MUST NOT use any information from a token that has expired. The subject’s authorities on resources and operations are represented by additional JWT claims with a name identifying the resource or operation and a value containing the activities the subject is allowed to perform. The following activities are supported:\nREAD - The client is allowed to establish a receiving link using the resource’s node address as the link’s source address. WRITE - The client is allowed to establish a sending link using the resource’s node address as the link’s target address. EXECUTE - The client is allowed to invoke an operation on an endpoint, i.e. send a message over a link with a subject representing the operation name and the link’s target address representing the API endpoint’s node address. The allowed activities are encoded in a claim’s value by means of simply concatenating the activities’ initial characters (R, W, E).\nThe token may contain any number of additional claims which may be ignored by clients that do not understand their meaning.\nResource Authorities A client’s authority on a resource is represented by a JWT claim with a name containing the resource node address prefixed with r: and a value containing the activities the client is allowed to perform on the resource. The node address MAY contain one or more wildcard (*) characters to represent any string.\nExample:\nAssuming a client which is allowed to\nsend and consume events for tenant my-tenant and consume telemetry data for all tenants the corresponding claims (in the token’s JSON representation) would look like this:\n{ ... \"r:event/my-tenant\": \"RW\", \"r:telemetry/*\": \"R\", ... } Operation Authorities A client’s authority to invoke an endpoint’s operation(s) is represented by a JWT claim with a name containing the endpoint’s node address and operation identifier prefixed with o: and a value of E (for EXECUTE). The endpoint node address MAY contain one or more wildcard (*) characters to represent any string. The operation identifier is the subject value defined by the corresponding API for the operation. The operation identifier MAY be set to * to represent any operation of the endpoint.\nExample:\nAssuming a client which is allowed to\ninvoke the Device Registration API’s assert Registration operation for any tenant and invoke all methods of the Credentials API for tenant my-tenant the corresponding claims (in the token’s JSON representation) would look like this:\n{ ... \"o:registration/*:assert\": \"E\", \"o:credentials/my-tenant:*\": \"E\", ... } ",
    "description": "",
    "tags": null,
    "title": "Authentication API Specification",
    "uri": "/hono/docs/2.7/api/authentication/"
  },
  {
    "content": " ",
    "description": "",
    "tags": null,
    "title": "Device Registry Management API Specification",
    "uri": "/hono/docs/2.7/api/management/"
  },
  {
    "content": "Eclipse Hono™’s components report several metrics which may be used to gain some insight into the running system. For instance, the HTTP adapter reports the number of successfully processed telemetry messages. Some of these metrics are considered part of Hono’s external interface. This section describes the semantics and format of the metrics, how they can be retrieved and how to interpret actual values.\nReported Metrics Hono uses Micrometer for collecting metrics. Those metrics can be exported to different back ends. Please refer to Configuring Metrics for details.\nThe container images published on Docker Hub have been compiled with support for Prometheus as the metrics back end.\nWhen deploying to Kubernetes/OpenShift, the metrics reported by Hono may contain environment specific tags (like the pod name) which are added by the Prometheus scraper. However, those tags are not part of the Hono metrics definition.\nHono applications may report other metrics in addition to the ones defined here. In particular, all components report metrics regarding the JVM’s internal state, e.g. memory consumption and garbage collection status. Those metrics are not considered part of Hono’s official metrics definition. However, all those metrics will still contain the common tags described below.\nCommon Metrics Tags for common metrics are:\nTag Value Description host string The name of the host that the component reporting the metric is running on component-type adapter, service The type of component reporting the metric component-name string The name of the component reporting the metric. The names of Hono’s standard components are as follows:\nComponent component-name Auth Server hono-auth Device Registry hono-registry Command Router hono-command-router AMQP adapter hono-amqp CoAP adapter hono-coap HTTP adapter hono-http MQTT adapter hono-mqtt Lora adapter hono-lora Sigfox adapter hono-sigfox Protocol Adapter Metrics Additional tags used for metrics reported by protocol adapters are:\nName Value Description direction one-way, request, response The direction in which a Command \u0026 Control message is being sent:\none-way indicates a command sent to a device for which the sending application doesn’t expect to receive a response.\nrequest indicates a command request message sent to a device.\nresponse indicates a command response received from a device. qos 0, 1, unknown The quality of service used for a telemetry or event message.\n0 indicates at most once,\n1 indicates at least once and\nnone indicates unknown delivery semantics. status forwarded, unprocessable, undeliverable The processing status of a message.\nforwarded indicates that the message has been forwarded to a downstream consumer\nunprocessable indicates that the message has not been processed not forwarded, e.g. because the message was malformed\nundeliverable indicates that the message could not be forwarded, e.g. because there is no downstream consumer or due to an infrastructure problem tenant string The identifier of the tenant that the metric is being reported for. ttd command, expired, none A status indicating the outcome of processing a TTD value contained in a message received from a device.\ncommand indicates that a command for the device has been included in the response to the device’s request for uploading the message.\nexpired indicates that a response without a command has been sent to the device.\nnone indicates that either no TTD value has been specified by the device or that the protocol adapter does not support it. type command_response, credentials, event, registration, telemetry, tenant The type of message that the metric is being reported for. Additional tags for hono.connections.attempts:\nName Value Description cipher-suite string The name of the cipher suite that is used for the device’s connection to the adapter. The specific value depends on the TLS implementation used by the protocol adapter.The value UNKNOWN is used if the connection does not use TLS or the cipher suite could not be determined, e.g. because the connection attempt failed before the cipher suite has been negotiated. outcome adapter-disabled, connection-duration-exceeded,data-volume-exceeded, registration-assertion-failure,succeeded, tenant-connections-exceeded,unauthorized, unavailable, unknown The outcome of a device’s connection attempt.adapter-connections-exceeded indicates that the maximum number of connections that the adapter instance can handle are exceededadapter-disabled indicates that the protocol adapter is not enabled for the device’s tenantconnection-duration-exceeded indicates that the overall amount of time that a tenant’s devices may be connected to an adapter has exceededdata-volume-exceeded indicates that the overall amount of data that a tenant’s device may transfer per time period has exceededregistration-assertion-failure indicates that the device is either unknown or disabledsucceeded indicates a successfully established connectiontenant-connections-exceeded indicates that the maximum number of devices that may be connected simultaneously for a tenant has been exceededunauthorized indicates that the device failed to authenticateunavailable indicates that some of Hono’s (required) services are not availableunknown indicates an unknown reason. Additional tags for hono.amqp.delivery.duration:\nName Value Description outcome received, accepted, rejected, released, modified, declared, transactionalState, and aborted Any of the AMQP 1.0 disposition states, as well as aborted, in the case the connection/link was closed before the disposition could be read. Metrics provided by the protocol adapters are:\nMetric Type Tags Description hono.amqp.delivery.duration Timer host, component-type, component-name, tenant, type, outcome The time it took to send an AMQP 1.0 message and receive the remote peers disposition. hono.amqp.nocredit Counter host, component-type, component-name, tenant, type The number of times an AMQP 1.0 message should be sent, but could not because the sender was out of credit. hono.amqp.timeout Counter host, component-type, component-name, tenant, type The number of times sending an AMQP 1.0 message timed out, meaning that no disposition was received in the appropriate amount of time. hono.command.payload DistributionSummary host, component-type, component-name, tenant, type, status, direction The number of bytes conveyed in the payload of a command message. hono.command.processing.duration Timer host, component-type, component-name, tenant, type, status, direction The time it took to process a message conveying a command or a response to a command. hono.connections.authenticated Gauge host, component-type, component-name, tenant Current number of connected, authenticated devices. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. hono.connections.unauthenticated Gauge host, component-type, component-name Current number of connected, unauthenticated devices. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. hono.connections.authenticated.duration Timer host, component-type, component-name, tenant The overall amount of time that authenticated devices have been connected to protocol adapters. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. hono.connections.attempts Counter host, component-type, component-name, tenant, outcome, cipher-suite The number of attempts made by devices to connect to a protocol adapter. The outcome tag’s value determines if the attempt was successful or not. In the latter case the outcome also indicates the reason for the failure to connect.NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. hono.telemetry.payload DistributionSummary host, component-type, component-name, tenant, type, status The number of bytes conveyed in the payload of a telemetry or event message. hono.telemetry.processing.duration Timer host, component-type, component-name, tenant, type, status, qos, ttd The time it took to process a message conveying telemetry data or an event. Minimum Message Size If a minimum message size is configured for a tenant, then the payload size of the telemetry, event and command messages are calculated in accordance with the configured value and then reported to the metrics by the AMQP, HTTP and MQTT protocol adapters. If minimum message size is not configured for a tenant then the actual message payload size is reported.\nAssume that the minimum message size for a tenant is configured as 4096 bytes (4KB). The payload size of an incoming message with size 1KB is calculated as 4KB by the protocol adapters and reported to the metrics system. For an incoming message of size 10KB, it is reported as 12KB.\nService Metrics Authentication Server Metric Type Tags Description hono.authentication.attempts Counter host, component-type, component-name, outcome, client-type The number of attempts made by clients to authenticate to the server.The outcome tag’s value determines if the attempt was successful or not:succeeded indicates that the client has been authenticated successfully,unauthorized indicates that the client failed to authenticate, e.g. because of wrong credentials andunavailable indicates that some of the services required for verifying the client’s credentials are (temporarily) not available.The client-type tag indicates what type of client has attempted to authenticate:auth-service indicates that the client tried to use the server as an implementation of the Hono Authentication Service,dispatch-router indicates that the client tried to use the server as an implementation of the Qpid Dispatch Router AuthService.unknown indicates that the type of client is unknown. Command Router Command messages get first received by the Command Router component and then get forwarded to the matching protocol adapter instance, where the command will be reflected in the corresponding protocol adapter metrics with the hono.command prefix. If the command could not be forwarded to a protocol adapter, the Command Router will report the command in its metrics, as listed below.\nMetric Type Tags Description hono.command.payload DistributionSummary host, component-type, component-name, tenant, type, status, direction The number of bytes conveyed in the payload of a command message that could not be forwarded to a protocol adapter. hono.command.processing.duration Timer host, component-type, component-name, tenant, type, status, direction The time it took to process a message conveying a command that could not be forwarded to a protocol adapter. Device Registry Metric Type Tags Description hono.tenants.total Gauge host, component-type, component-name The total number of tenants registered. All registry instances will report the same (total) number of tenants so no aggregation along the host dimension should be performed. ",
    "description": "",
    "tags": null,
    "title": "Metrics",
    "uri": "/hono/docs/2.7/api/metrics/"
  },
  {
    "content": "Deployment Learn how to deploy Eclipse Hono™ to various container orchestration platforms.\n",
    "description": "",
    "tags": null,
    "title": "Deployment",
    "uri": "/hono/docs/2.7/deployment/"
  },
  {
    "content": "Eclipse Hono™’s components are provided as container images which can be run on arbitrary container orchestration platforms. The Helm package manager can be used to install Hono to a Kubernetes cluster by means of the chart maintained in the Eclipse IoT Packages™ chart repository.\nPlease refer to the chart’s README for instructions regarding installation and configuration.\n",
    "description": "",
    "tags": null,
    "title": "Helm based Deployment",
    "uri": "/hono/docs/2.7/deployment/helm-based-deployment/"
  },
  {
    "content": "The OpenShift specific deployment using the source-to-image (S2I) model has been dropped in Hono version 1.0 in favor of the Helm charts and the Eclipse IoT Packages™ project.\nYou can still deploy to OpenShift and OKD, using the Helm charts. And you can also use routes to expose services. Deploying using S2I is also still possible, however the Hono project simply no longer provides out-of-the box scripts for doing so.\n",
    "description": "",
    "tags": null,
    "title": "OpenShift / OKD",
    "uri": "/hono/docs/2.7/deployment/openshift/"
  },
  {
    "content": "A common option for running Eclipse Hono™ is to install it to a Kubernetes cluster. Please refer to the Eclipse IoT Packages™ project for an overview of options for setting up a Kubernetes environment that Hono can be installed to.\n",
    "description": "",
    "tags": null,
    "title": "Setting up a Kubernetes Cluster",
    "uri": "/hono/docs/2.7/deployment/create-kubernetes-cluster/"
  },
  {
    "content": "Deploying Eclipse Hono™ to a container orchestration platform is easy thanks to the provided Docker images. This page provides some guidance for configuring the resource consumption of these containers in order to make sure that they get enough memory and CPU to run properly, but to also make sure that individual containers do not use up all the resources causing other containers to starve.\nDocker itself provides means to limit a container’s consumption of memory and CPU resources by means of command line options that can be set when starting up a container. Both Kubernetes and OpenShift leverage this mechanism when defining resource limits of a pod. Please refer to the corresponding documentation of Docker, Kubernetes and OpenShift for details regarding the particular syntax to be used.\nJava’s View of the World Hono’s service components are implemented in Java. When the corresponding Docker container for such a service is started, the only process being run inside the container is therefore a Java virtual machine (JVM). On startup, the JVM tries to determine the amount of memory and the number of CPU cores that it can use to execute workloads. By default the JVM queries the operating system for the corresponding parameters and adjusts its runtime parameters accordingly, e.g. it will by default limit the size of its heap memory to a quarter of the total memory available in order to leave enough memory for other processes running on the same system.\nThis is a reasonable approach when running on bare metal or a VM where other processes are expected to be running on the same machine, thus competing for the same computing resources. However, containers are usually configured to run a single process only so that it makes more sense to dedicate almost all of the available resources to running that process, leaving the (small) rest for the operating system itself.\nAs described above, a Docker container can easily be configured with a limit for memory and CPU resources that it may use during runtime. These limits are set and enforced using Linux CGroups.\nLimiting a Component’s Memory Consumption Starting with Java 9, the JVM will correctly determine the total memory and number of CPUs available when running inside of a container. All of the Docker images provided by Hono run with OpenJDK 11 by default, thus ensuring that the JVM considers any memory limits configured for the container when configuring its heap during startup. However, the default algorithm will still only allocate a quarter of the (limited) amount of memory, thus leaving a lot of memory available to the container unused.\nThe following JVM options can be used in Java 9 and later in order to change this behavior:\n-XX:MinRAMPercentage, -XX:MaxRAMPercentage and -XX:InitialRAMPercentage can be used to set the (minimum, maximum and initial) percentage of total memory that may be allocated for the heap. A value of 70-80% should work if no other processes are running in the same container. Kubernetes In Kubernetes (and OpenShift) the resource limits for a pod, and thus the container(s) that are part of the pod, can be configured in the corresponding PodSpec. The following excerpt from the HTTP adapter’s Kubernetes Deployment resource descriptor illustrates the mechanism:\napiVersion: apps/v1 kind: Deployment metadata: name: hono-adapter-http spec: template: metadata: labels: app.kubernetes.io/component: adapter-http app.kubernetes.io/instance: eclipse-hono app.kubernetes.io/managed-by: Helm app.kubernetes.io/name: hono app.kubernetes.io/version: 2.0.0 helm.sh/chart: hono-2.7.0 spec: containers: - image: index.docker.io/eclipsehono/hono-adapter-http:2.7.0 name: adapter-http resources: limits: cpu: \"1\" memory: \"300Mi\" requests: cpu: \"150m\" memory: \"300Mi\" ports: - containerPort: 8088 name: health protocol: TCP - containerPort: 8080 name: http protocol: TCP - containerPort: 8443 name: https protocol: TCP env: - name: JDK_JAVA_OPTIONS value: -XX:MinRAMPercentage=80 -XX:MaxRAMPercentage=80 - name: KUBERNETES_NAMESPACE valueFrom: fieldRef: apiVersion: v1 fieldPath: metadata.namespace - name: QUARKUS_CONFIG_LOCATIONS value: /opt/hono/default-logging-config/logging-quarkus-dev.yml volumeMounts: - mountPath: /opt/hono/config name: conf readOnly: true volumes: - name: adapter-http-conf secret: defaultMode: 420 secretName: eclipse-hono-adapter-http-conf The resources property defines the overall limit of 300 MB of memory that the pod may use. The JDK_JAVA_OPTIONS environment variable is used to configure the JVM to use 80% of the total memory for its heap.\nLimiting the Number of Device Connections Hono supports limiting the overall number of simultaneously connected devices per tenant. Please refer to the connections limit concept for more information. The limit needs to be configured at the tenant level using the resource-limits configuration property. Please refer to the Tenant API for configuration details.\nLimiting the Overall Connection Time Hono supports configuring limits based on the overall amount of time that the devices have already been connected to protocol adapters for a tenant. Please refer to the connection duration limit for more information. Before accepting any connection requests from the devices, the protocol adapters verify that the configured connection duration limit is not exceeded. If the limit has been already reached, then the connection request is rejected. The limit needs to be configured at the tenant level using the resource-limits configuration property. Please refer to the Tenant API for configuration details.\nLimiting the Data Volume Hono supports limiting the amount of data that devices of a tenant can publish to Hono during a given time interval. Please refer to the messages limit concept for more information. The limit needs to be configured at the tenant level using the resource-limits configuration property. Please refer to the Tenant API for configuration details.\n",
    "description": "",
    "tags": null,
    "title": "Limiting Resource Usage",
    "uri": "/hono/docs/2.7/deployment/resource-limitation/"
  },
  {
    "content": "Architecture Get an overview of the architecture of Eclipse Hono™.\n",
    "description": "",
    "tags": null,
    "title": "Architecture",
    "uri": "/hono/docs/2.7/architecture/"
  },
  {
    "content": "This page describes the high level components constituting an Eclipse Hono™ instance and their relations to each other.\nTop Level The diagram below provides an overview of the top level logical components.\nThe MQTT and HTTP Adapters use the Device Registry to authenticate Devices connecting to the adapters and asserting their registration status. The adapters then forward the telemetry data and events received from the devices to the Messaging Infrastructure for delivery to Business Applications. Business applications also use the messaging infrastructure to send commands to connected devices. Commands are first received by the Command Router and then forwarded to the protocol adapter instance that the target device is connected to.\nThe Device Registry and the Command Router use the Auth Server to authenticate the protocol adapters during connection establishment.\nAll interactions between the components are based on AMQP 1.0 message exchanges as defined by the\nCredentials API, Tenant API, Device Registration API, Command Router API, Command \u0026 Control API, Telemetry API and Event API. Device Registry The diagram below provides an overview of the Mongo DB based Device Registry component’s internal structure.\nThe Mongo DB based Device Registry component implements the AMQP 1.0 based Credentials, Tenant and Device Registration APIs which are used by Hono’s protocol adapters to authenticate devices. It also implements the HTTP based Device Registry Management API which is used by administrators to provision and manage device data. Clients opening a connection to the Device Registry AMQP Server are authenticated by means of an external service accessed via the Authentication port.\nPlease refer to the Device Registry user guide for details.\nCommand Router The diagram below provides an overview of the Command Router component’s internal structure.\nThe Command Router component implements the Command Router API. Clients opening a connection to the CommandRouterServer are authenticated by means of an external service accessed via the Auth port.\nThe Command Router component uses the Device Registry via the Tenant API and the Device Registration API and is connected to the Messaging Infrastructure to receive and forward Command \u0026 Control messages as defined by the Command \u0026 Control API.\nMessaging Infrastructure The Messaging Infrastructure is not per se a component being developed as part of Hono. Instead, Hono supports Kafka, AMQP 1.0 and/or Google Pub/Sub based messaging infrastructure that is being developed by other open source projects.\nKafka based Messaging Infrastructure The example deployment currently employs the bitnami Kafka Helm chart for installing a single-node Apache Kafka™ broker instance. Note that this setup is suitable for development purposes but will probably not meet requirements regarding e.g. scalability of real world use cases.\nScaling out messaging infrastructure is a not a trivial task. Hono does not provide an out-of-the-box solution to this problem. Please refer to the Helm chart’s documentation for details regarding the set up of a cluster for production purposes.\nAMQP 1.0 based Messaging Infrastructure The example deployment currently uses a single Apache Qpid™ Dispatch Router instance connected to a single Apache ActiveMQ™ Artemis broker instance. Note that this setup is suitable for development purposes but will probably not meet requirements regarding e.g. scalability of real world use cases.\nThe diagram below provides an overview of the default implementation of the Messaging Network component used with Hono.\nScaling out messaging infrastructure is a not a trivial task. Hono does not provide an out-of-the-box solution to this problem but instead integrates with the EnMasse project which aims at providing Messaging as a Service infrastructure.\nGoogle Pub/Sub based Messaging Infrastructure To use this setup, a Google project has to be provided with the Pub/Sub API enabled. There is no example deployment for this Messaging Infrastructure.\nGoogle Pub/Sub is an asynchronous messaging service designed to be highly scalable. There is no need to take care about scaling out messaging infrastructure.\nWarning Support for Google Pub/Sub based messaging infrastructure is considered experimental and may change without further notice.\n",
    "description": "",
    "tags": null,
    "title": "Component View",
    "uri": "/hono/docs/2.7/architecture/component-view/"
  },
  {
    "content": "This page describes how authentication and authorization of devices, consumers (back end applications) and system components works in Hono.\nRequirements Devices are authenticated and authorized when they connect to a protocol adapter. Consumers are authenticated and authorized when they connect to a Dispatch Router instance. System components are authenticated and authorized when they connect to each other. Credentials and authorization rules can be managed centrally, i.e. credentials and rules do not need to be configured manually for each component. How it works today The following diagram provides an overview of the components involved in use cases requiring authentication and authorization.\nDevice Auth Both the HTTP adapter as well as the MQTT adapter require devices to authenticate during connection establishment by default. Both rely on the Credentials API to help in verifying credentials provided by a device. Please refer to Device Authentication for a general overview of Hono’s approach to authenticating devices and to the protocol adapter user guides for specifics regarding how devices can authenticate to the corresponding protocol adapters.\nSystem Component Auth Client components opening an AMQP connection to a server component are authenticated using SASL PLAIN as specified in RFC 4422. The server component takes the authentication information provided by the client component and opens a connection to the Auth Server, using the credentials provided by the client in its SASL PLAIN exchange with the server component. On successful authentication the Auth Server issues a JSON Web Token (JWT) asserting the client’s identity and its granted authorities to the server component. The server component then attaches this token to its AMQP connection with the client and from then on uses it to make authorization decisions regarding the client’s requests. See Authentication API for details regarding the authentication process and the format of the tokens issued by the Auth Server.\nBased on the components shown above, the following sequence diagram shows how the MQTT Adapter connects to the Device Registry and gets authenticated transparently using the Auth Server.\nClient components are authorized whenever they open a new AMQP link on an existing connection to the server. When a client tries to open a receiver link, the server checks if the client is authorized to read from the source address the client has specified in its AMQP attach frame. Analogously, when a client tries to open a sender link, the server checks if the client is authorized to write to the target address from the client’s attach frame.\nService implementations may additionally authorize individual (request) messages received from the client, e.g. based on the message’s subject property which is used by Hono’s AMQP 1.0 based APIs to indicate the operation to invoke. In such a case the server checks if the client is authorized to execute the operation indicated by the message subject on the link’s target address.\nApplication Auth Business Applications connect to the Messaging Infrastructure in order to consume telemetry data and events and send commands to devices. It is therefore the responsibility of the Messaging Infrastructure to properly authenticate and authorize the application.\nHono supports both Apache Kafka™ as well as AMQP 1.0 based Messaging Infrastructure. In the latter case, the example deployment uses Apache Qpid™ Dispatch Router and Apache ActiveMQ™ Artemis as the implementation of the Messaging Infrastructure.\nKafka based Messaging Infrastructure When using the Kafka based example deployment the Kafka broker is responsible for authenticating connections from applications. For this purpose, the broker can be configured to authenticate clients using arbitrary SASL mechanisms. Access to addresses for receiving messages can be restricted to certain identities.\nThe Kafka broker instance which is used in the example deployment is configured to use the SASL PLAIN mechanism for authenticating clients based on a static list of user names and corresponding passwords.\nPlease refer to the Kafka documentation for details regarding configuration of Kafka broker security.\nAMQP 1.0 based Messaging Infrastructure When using the AMQP 1.0 based example deployment, an Apache Qpid™ Dispatch Router and an Apache ActiveMQ™ Artemis broker instance are used as the implementation of the Messaging Infrastructure. The Dispatch Router instance is responsible for authenticating connections from applications. For this purpose, the router can be configured to authenticate clients using arbitrary SASL mechanisms. Access to addresses for receiving messages can be restricted to certain identities.\nThe Dispatch Router instance used in the example deployment is configured to delegate authentication of clients to the Auth Server by means of its Auth Service Plugin mechanism. This mechanism works in a very similar way as described above for the authentication of system components. The main difference is that the clients' authorities are not transferred by means of a JSON Web Token but instead are carried in a property of the Auth Server’s AMQP open frame.\nPlease refer to the Dispatch Router documentation for details regarding configuration of Dispatch Router security.\nManagement of Identities and Authorities The identities and corresponding authorities that the Auth Server uses for verifying credentials and issuing tokens are defined in a configuration file read in during start-up of the Auth Server. These authorities are used for authenticating and authorizing system components. They are also used for authenticating Business Applications when using AMQP 1.0 based Messaging Infrastructure.\nAn example configuration file can be found in the Auth Server code base.\nFuture Approach In the long run Hono will still use tokens for authenticating clients but will use a policy based approach for authorizing requests, i.e. authorization decisions will be made by a central policy enforcement component. Hono services will pass in the client’s token, the resource being accessed and the intended action along with potentially other attributes to the policy enforcement component which will then make the authorization decision based on the configured rules (policy) and return the outcome to the component.\n",
    "description": "",
    "tags": null,
    "title": "Authentication/Authorization",
    "uri": "/hono/docs/2.7/architecture/auth/"
  },
  {
    "content": "",
    "description": "",
    "tags": null,
    "title": "Categories",
    "uri": "/hono/docs/2.7/categories/"
  },
  {
    "content": "The Device Connection API is used by Protocol Adapters to set and retrieve information about the connections from devices or gateways to the protocol adapters.\nInfo The Device Connection API has been replaced by the Command Router API.\nThe Device Connection API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to the Device Connection service component using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.\nPreconditions for invoking the Device Connection API Client has established an AMQP connection with the Device Connection service. Client has established an AMQP link in role sender on the connection using target address device_con/${tenant_id}. This link is used by the client to send commands concerning device connections to Hono. Client has established an AMQP link in role receiver on the connection using source address device_con/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Device Connection service. This link’s source address is also referred to as the reply-to address for the request messages. Client connecting to Device Connection service Set last known Gateway for Device Clients use this command to set the gateway that last acted on behalf of a given device.\nAs this operation is invoked frequently by Hono’s components, implementors may choose to keep this information in memory. This API doesn’t mandate checks on the validity of the given device or gateway IDs in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient sets the last known gateway for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to set the last known gateway for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to set-last-gw. gateway_id yes application-properties string The identifier of the gateway that last acted on behalf of the device identified by the device_id property. If a device connects directly instead of through a gateway, the device’s identifier MUST be specified here. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a set last known gateway for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the last known gateway for the device has been updated. 400 Bad Request, the last known gateway has not been updated due to invalid or missing data in the request. Implementors of this API may return a 404 status code in order to indicate that no device and/or gateway with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nGet last known Gateway for Device Clients use this command to retrieve the gateway that last acted on behalf of a given device.\nMessage Flow\nClient retrieving the last known gateway for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to retrieve the last known gateway for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to get-last-gw. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a get last known gateway for device request contains the Standard Response Properties as well as the properties shown in the following table:\nName Mandatory Location AMQP Type Description content-type no properties string MUST be set to application/json if the invocation of the operation was successful and the body of the response message contains payload as described below. The result of a successful invocation is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.\nThe response message JSON object has the following properties:\nName Mandatory JSON Type Description gateway-id yes string The ID of the last known gateway for the device. last-updated no string The date that the information about the last known gateway for the device was last updated. The value MUST be an ISO 8601 compliant combined date and time representation in extended format. The response message’s status property may contain the following codes:\nCode Description 200 OK, the payload contains the gateway ID. 400 Bad Request, the request message does not contain all required information/properties. 404 Not Found, there is no last known gateway assigned to the device. Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nSet command-handling protocol adapter instance for device Clients use this command to set the protocol adapter instance that currently handles command \u0026 control messages for a given device.\nClients can provide an optional lifespan parameter to make the protocol adapter instance entry expire after the given number of seconds. Note that implementations of this API have to support this feature, otherwise protocol adapters, as the clients of this API, might fail to correctly route command messages.\nThis API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient sets the command-handling protocol adapter instance for device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to set the command-handling protocol adapter instance for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to set-cmd-handling-adapter-instance. adapter_instance_id yes application-properties string The identifier of the protocol adapter instance that currently handles commands for the device or gateway identified by the device_id property. lifespan no application-properties int The lifespan of the mapping entry in seconds. After that period, the mapping entry shall be treated as non-existent by the Device Connection API methods. A negative value, as well as an omitted property, is interpreted as an unlimited lifespan. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a set command-handling adapter instance for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the command-handling adapter instance for the device has been updated. 400 Bad Request, the adapter instance for the device has not been set or updated due to invalid or missing data in the request. Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nRemove command-handling protocol adapter instance for device Clients use this command to remove the information, which protocol adapter instance is currently handling command \u0026 control messages for the given device. The mapping information is only removed, if the currently associated adapter instance matches the one given in the request.\nThis API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.\nMessage Flow\nClient removes the command-handling protocol adapter instance information for device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to remove the mapping information regarding the command-handling protocol adapter instance for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to remove-cmd-handling-adapter-instance. adapter_instance_id yes application-properties string The identifier of the protocol adapter instance to remove the mapping information for. Only if this adapter instance is currently associated with the device or gateway identified by the device_id property, the mapping entry will be removed. The body of the message SHOULD be empty and will be ignored if it is not.\nResponse Message Format\nA response to a remove command-handling adapter instance for device request contains the Standard Response Properties.\nThe response message’s status property may contain the following codes:\nCode Description 204 OK, the adapter instance mapping information for the device has been removed. 400 Bad Request, the request message does not contain all required properties. 412 Precondition failed, the adapter instance for the device has not been removed because there is no matching command-handling adapter instance assigned to the device. Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nGet command-handling protocol adapter instances for device Clients use this command to get information about the adapter instances that can handle command \u0026 control messages for the given device.\nAs part of the request message, the client is supposed to provide the list of gateways that may act on behalf of the given device. The client may get this list via the Device Registration API’s assert Device Registration operation.\nThis API doesn’t mandate checks on the validity of the given device and the gateway list in order not to introduce a dependency on the Device Registration API.\nThe command implementation MUST determine the adapter instances by applying the following rules (in the given order):\nIf an adapter instance is associated with the given device, this adapter instance is returned as the single returned list entry. Otherwise, if there is an adapter instance registered for the last known gateway associated with the given device, this adapter instance is returned as the single returned list entry. The last known gateway has to be contained in the given list of gateways for this case. Otherwise, all adapter instances associated with any of the given gateway identifiers are returned. That means that for a device communicating via a gateway, the result is reduced to a single element list if an adapter instance for the device itself or its last known gateway is found. The adapter instance registered for the device itself is given precedence in order to ensure that a gateway having subscribed to commands for that particular device is chosen over a gateway that has subscribed to commands for all devices of a tenant.\nMessage Flow\nClient retrieving the list of command-handling adapter instances for a device Request Message Format\nThe following table provides an overview of the properties a client needs to set on a message to retrieve the command-handling adapter instances for a device in addition to the Standard Request Properties.\nName Mandatory Location AMQP Type Description content-type yes properties string MUST be set to application/json. subject yes properties string MUST be set to get-cmd-handling-adapter-instances. The body of the message MUST consist of a single AMQP Data section containing a UTF-8 encoded string representation of a single JSON object. The JSON object has the following properties:\nName Mandatory JSON Type Description gateway-ids yes array The IDs of the gateways that may act on behalf of the given device. This list may be obtained via the Device Registration API’s assert Device Registration operation. Example of a request payload:\n{ \"gateway-ids\": [\"gw-1\", \"gw-2\", \"gw-3\"] } Response Message Format\nA response to a get command-handling adapter instances for device request contains the Standard Response Properties as well as the properties shown in the following table:\nName Mandatory Location AMQP Type Description content-type no properties string MUST be set to application/json if the invocation of the operation was successful and the body of the response message contains payload as described below. The result of a successful invocation is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.\nThe response message JSON object has the following properties:\nName Mandatory JSON Type Description adapter-instances yes array A non-empty array of JSON objects that represent the command-handling adapter instances along with the device or gateway id. Each entry in the adapter-instances array has the following properties:\nName Mandatory JSON Type Description adapter-instance-id yes string The ID of the protocol adapter instance handling command \u0026 control messages for the device given in the device-id property. device-id yes string The ID of the gateway or device that the protocol adapter instance given by the adapter-instance-id is handling command \u0026 control messages for. This ID is not necessarily the device_id given in the request message, it may be the ID of one of the gateways acting on behalf of the device. An example of a response message with a single adapter instance result, returned for example if an adapter instance is registered for the given device:\n{ \"adapter-instances\": [ { \"adapter-instance-id\": \"adapter-1\", \"device-id\": \"4711\" } ] } An example of a response message with multiple contained adapter instances, returned for example if no adapter instance is registered for the given device or its last used gateway, and therefore a list of all adapter instances for the gateways of the device is returned:\n{ \"adapter-instances\": [ { \"adapter-instance-id\": \"adapter-1\", \"device-id\": \"gw-1\" }, { \"adapter-instance-id\": \"adapter-1\", \"device-id\": \"gw-2\" } ] } The response message’s status property may contain the following codes:\nCode Description 200 OK, the payload contains the adapter instances. 400 Bad Request, the request message does not contain all required information/properties. 404 Not Found, there is no command-handling adapter instance assigned to the device. Implementors of this API may also return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.\nFor status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.\nStandard Message Properties Due to the nature of the request/response message pattern of the operations of the Device Connection API, there are some standard properties shared by all of the request and response messages exchanged as part of the operations.\nStandard Request Properties The following table provides an overview of the properties shared by all request messages regardless of the particular operation being invoked.\nName Mandatory Location AMQP Type Description subject yes properties string MUST be set to the value defined by the particular operation being invoked. correlation-id no properties message-id MAY contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used. Either this or the message-id property MUST be set. message-id no properties string MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the correlation-id property MUST be set. reply-to yes properties string MUST contain the source address that the client wants to received response messages from. This address MUST be the same as the source address used for establishing the client’s receive link (see Preconditions). device_id yes application-properties string MUST contain the ID of the device that is subject to the operation. Standard Response Properties The following table provides an overview of the properties shared by all response messages regardless of the particular operation being invoked.\nName Mandatory Location AMQP Type Description correlation-id yes properties message-id Contains the message-id (or the correlation-id, if specified) of the request message that this message is the response to. status yes application-properties int Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined for each particular operation. cache_control no application-properties string Contains an RFC 2616 compliant cache directive. The directive contained in the property MUST be obeyed by clients that are caching responses. Delivery States Hono uses the following AMQP message delivery states when receiving request messages from clients:\nDelivery State Description ACCEPTED Indicates that the request message has been received and accepted for processing. REJECTED Indicates that Hono has received the request but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case. ",
    "description": "",
    "tags": null,
    "title": "Device Connection API Specification",
    "uri": "/hono/docs/2.7/api/device-connection/"
  },
  {
    "content": "The Device Connection service provides an implementation of Eclipse Hono™’s Device Connection API.\nProtocol adapters use this API to store and retrieve information about the gateway that a device is using to connect to Hono’s protocol adapters. This information is necessary for routing commands to the particular protocol adapter instance that the gateway used by the device is connected to.\nInfo The Device Connection service has been removed in Hono 2.0.0. Protocol adapters now use the Command Router service instead.\nThe Device Connection component provides a production grade implementation of the Device Connection API which uses a remote data grid for storing information about device connections. The data grid can be scaled out independently from the Device Connection service components to meet the storage demands at hand.\nThe Device Connection component is implemented as a Spring Boot application. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the Device Connection component.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of Verticle instances to deploy. If not set, one Verticle per processor core is deployed. HONO_DEVICECONNECTION_AMQP_BINDADDRESS\nhono.deviceConnection.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_DEVICECONNECTION_AMQP_CERTPATH\nhono.deviceConnection.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_DEVICECONNECTION_AMQP_KEYPATH.\nAlternatively, the HONO_DEVICECONNECTION_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_DEVICECONNECTION_AMQP_INSECUREPORT\nhono.deviceConnection.amqp.insecurePort no - The insecure port the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_DEVICECONNECTION_AMQP_INSECUREPORTBINDADDRESS\nhono.deviceConnection.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_DEVICECONNECTION_AMQP_INSECUREPORTENABLED\nhono.deviceConnection.amqp.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_DEVICECONNECTION_AMQP_INSECUREPORT or the default AMQP port number (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_DEVICECONNECTION_AMQP_KEYPATH\nhono.deviceConnection.amqp.keyPath no - 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_DEVICECONNECTION_AMQP_CERTPATH. Alternatively, the HONO_DEVICECONNECTION_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_DEVICECONNECTION_AMQP_KEYSTOREPASSWORD\nhono.deviceConnection.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_DEVICECONNECTION_AMQP_KEYSTOREPATH\nhono.deviceConnection.amqp.keyStorePath no - 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_DEVICECONNECTION_AMQP_KEYPATH and HONO_DEVICECONNECTION_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_DEVICECONNECTION_AMQP_NATIVETLSREQUIRED\nhono.deviceConnection.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_DEVICECONNECTION_AMQP_PORT\nhono.deviceConnection.amqp.port no 5671 The secure port that the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_DEVICECONNECTION_AMQP_RECEIVERLINKCREDIT\nhono.deviceConnection.amqp.receiverLinkCredit no 100 The number of credits to flow to a client connecting to the service’s AMQP endpoint. HONO_DEVICECONNECTION_AMQP_SECUREPROTOCOLS\nhono.deviceConnection.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_DEVICECONNECTION_AMQP_SUPPORTEDCIPHERSUITES\nhono.deviceConnection.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Monitoring Options Port Configuration The Device Connection component supports configuration of an AMQP based endpoint that can be configured to listen for connections on\na 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.\nSecure Port Only The server needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_DEVICECONNECTION_AMQP_KEYSTOREPATH and the HONO_DEVICECONNECTION_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_DEVICECONNECTION_AMQP_KEYPATH and HONO_DEVICECONNECTION_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_DEVICECONNECTION_AMQP_PORT variable.\nThe HONO_DEVICECONNECTION_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 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).\nInsecure 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\nexplicitly setting HONO_DEVICECONNECTION_AMQP_INSECUREPORT to a valid port number, or by implicitly configuring the default AMQP port (5672) by simply setting HONO_DEVICECONNECTION_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if HONO_DEVICECONNECTION_AMQP_INSECUREPORT is set to the default secure AMQP port (5671).\nThe HONO_DEVICECONNECTION_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_DEVICECONNECTION_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The Device Connection component will then use arbitrary (unused) port numbers determined by the operating system during startup.\nData Grid Connection Configuration The Device Connection component requires either an embedded cache or a remote data grid, using the Infinispan Hotrod protocol to store device information.\nThe following table provides an overview of the configuration variables and corresponding system properties for configuring the common aspects of the service:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_DEVICECONNECTION_COMMON_CACHENAME\nhono.deviceConnection.common.cacheName no device-connection The name of the cache HONO_DEVICECONNECTION_COMMON_CHECKKEY\nhono.deviceConnection.common.checkKey no KEY_CONNECTION_CHECK The key used to check the health of the cache. This is only used in case of a remote cache. HONO_DEVICECONNECTION_COMMON_CHECKVALUE\nhono.deviceConnection.common.checkValue no VALUE_CONNECTION_CHECK The value used to check the health of the cache. This is only used in case of a remote cache. The type of the cache is selected on startup by enabling or disabling the profile embedded-cache. If the profile is enabled the embedded cache is used, otherwise the remote cache is being used. The remote cache is the default.\nRemote cache The following table provides an overview of the configuration variables and corresponding system properties for configuring the connection to the data grid:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_DEVICECONNECTION_REMOTE_SERVERLIST\nhono.deviceConnection.remote.serverList yes - A list of remote servers in the form: host1[:port][;host2[:port]]..... HONO_DEVICECONNECTION_REMOTE_AUTHSERVERNAME\nhono.deviceConnection.remote.authServerName yes - The server name to indicate in the SASL handshake when authenticating to the server. HONO_DEVICECONNECTION_REMOTE_AUTHREALM\nhono.deviceConnection.remote.authRealm yes - The authentication realm for the SASL handshake when authenticating to the server. HONO_DEVICECONNECTION_REMOTE_AUTHUSERNAME\nhono.deviceConnection.remote.authUsername yes - The username to use for authenticating to the server. HONO_DEVICECONNECTION_REMOTE_AUTHPASSWORD\nhono.deviceConnection.remote.authPassword yes - The password to use for authenticating to the server. In general, the service supports all configuration properties of the Infinispan Hotrod client using hono.deviceConnection.remote instead of the infinispan.client.hotrod prefix.\nEmbedded cache The following table provides an overview of the configuration variables and corresponding system properties for configuring the embedded cache:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_DEVICECONNECTION_EMBEDDED_CONFIGURATIONFILE\nhono.deviceConnection.embedded.configurationFile yes - The absolute path to an Infinispan configuration file. Also see the Infinispan Configuration Schema. Authentication Service Connection Configuration The Device Connection component requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.\nThe connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. Since Hono’s Authentication Service does not allow caching of the responses, the cache properties can be ignored.\nIn addition to the standard client configuration properties, following properties need to be set for the connection:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_VALIDATION_CERTPATH\nhono.auth.validation.certPath no - The absolute path to the PEM file containing the public key that the service should use for validating tokens issued by the Authentication service. Alternatively, a symmetric key can be used for validating tokens by setting the HONO_AUTH_VALIDATION_SHAREDSECRET variable. If none of these variables is set, the service falls back to the key indicated by the HONO_AUTH_CERTPATH variable. If that variable is also not set, startup of the service fails. HONO_AUTH_VALIDATION_SHAREDSECRET\nhono.auth.validation.sharedSecret no - A string to derive a symmetric key from which is used for validating tokens issued by the Authentication service. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the validation key using this variable, the Authentication service must be configured with the same key. Alternatively, an asymmetric key pair can be used for validating (and signing) by setting the HONO_AUTH_SIGNING_CERTPATH variable. If none of these variables is set, startup of the service fails. Metrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\n",
    "description": "",
    "tags": null,
    "title": "Configuring the Device Connection Service",
    "uri": "/hono/docs/2.7/admin-guide/device-connection-config/"
  },
  {
    "content": "The configuration of Eclipse Hono™s Device Registry implementations for the File Based Device Registry and for the MongoDB Based Device Registry.\n",
    "description": "",
    "tags": null,
    "title": "Device Registry Configurations",
    "uri": "/hono/docs/2.7/admin-guide/device-registry-config/"
  },
  {
    "content": "The Device Registry component provides exemplary implementations of Hono’s Tenant API, Device Registration API and Credentials API.\nAs such it exposes AMQP 1.0 based endpoints for retrieving the relevant information and persists data to the local file system.\nInfo The file based device registry has been removed in Hono 2.0.0. Please use the Mongo DB or JDBC based registry implementations instead.\nIn addition, the Device Registry also exposes HTTP resources for managing the contents of the registry according to the Device Registry Management API.\nWarning The Device Registry is not intended to be used in production environments. In particular, access to the HTTP resources described below is not restricted to authorized clients only.\nManaging Tenants Please refer to the Device Registry Management API for information about managing tenants.\nInfo The file based device registry does not support the Device Registry Management API’s search tenants operation.\nManaging Devices Please refer to the Device Registry Management API for information about managing devices.\nInfo The file based device registry does not support the Device Registry Management API’s search devices operation.\nManaging Credentials Please refer to the Device Registry Management API for information about managing credentials.\n",
    "description": "",
    "tags": null,
    "title": "File Based Device Registry",
    "uri": "/hono/docs/2.7/user-guide/file-based-device-registry/"
  },
  {
    "content": "The File based Device Registry component provides an exemplary implementation of Eclipse Hono™’s Device Registration, Credentials, Tenant and Device Connection APIs.\nProtocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.\nThere is no particular technical reason to implement these three APIs in one component, so for production scenarios there might be up to three different components each implementing one of the APIs.\nThe Device Registry component also exposes HTTP based resources for managing tenants and the registration information and credentials of devices.\nThe Device Registry is implemented as a Spring Boot application. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.\nInfo The file based device registry has been removed in Hono 2.0.0. Please use the Mongo DB or JDBC based registry implementations instead. The JDBC based registry can be configured to use an H2 database in either embedded or in-memory mode. The former can be used to persist data to the local file system while the latter keeps all data in memory only. Please refer to the H2 documentation for details.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the Device Registry.\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_APP_TYPE\nhono.app.type no file The device registry implementation to use. This may be either file or dummy. In the case of dummy a dummy implementation will be used which will consider all devices queried for as valid devices, having the access credentials hono-secret. Of course this shouldn’t be used for productive use. HONO_CREDENTIALS_SVC_CACHEMAXAGE\nhono.credentials.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_CREDENTIALS_SVC_FILENAME\nhono.credentials.svc.filename no /var/lib/hono/device-registry/\ncredentials.json The path to the file where the server stores credentials of devices. Hono tries to read credentials from this file during start-up and writes out all identities to this file periodically if property HONO_CREDENTIALS_SVC_SAVETOFILE is set to true.\nPlease refer to Credentials File Format for details regarding the file’s format. HONO_CREDENTIALS_SVC_HASHALGORITHMSWHITELIST\nhono.credentials.svc.hashAlgorithmsWhitelist no empty An array of supported hashing algorithms to be used with the hashed-password type of credentials. When not set, all values will be accepted. HONO_CREDENTIALS_SVC_MAXBCRYPTCOSTFACTOR\nhono.credentials.svc.maxBcryptCostFactor no 10 The maximum cost factor that is supported in password hashes using the BCrypt hash function. This limit is enforced by the device registry when adding or updating corresponding credentials. Increasing this number allows for potentially more secure password hashes to be used. However, the time required to compute the hash increases exponentially with the cost factor. HONO_CREDENTIALS_SVC_MAXBCRYPTITERATIONS\nhono.credentials.svc.maxBcryptIterations no 10 DEPRECATED Please use HONO_CREDENTIALS_SVC_MAXBCRYPTCOSTFACTOR instead.\nThe maximum cost factor that is supported in password hashes using the BCrypt hash function. This limit is enforced by the device registry when adding or updating corresponding credentials. Increasing this number allows for potentially more secure password hashes to be used. However, the time required to compute the hash increases exponentially with the cost factor. HONO_CREDENTIALS_SVC_MODIFICATIONENABLED\nhono.credentials.svc.modificationEnabled no true When set to false the credentials contained in the registry cannot be updated nor removed. HONO_CREDENTIALS_SVC_RECEIVERLINKCREDIT\nhono.credentials.svc.receiverLinkCredit no 100 The number of credits to flow to a client connecting to the Credentials endpoint. HONO_CREDENTIALS_SVC_SAVETOFILE\nhono.credentials.svc.saveToFile no false When set to true the server will periodically write out the registered credentials to the file specified by the HONO_CREDENTIALS_SVC_FILENAME property. HONO_CREDENTIALS_SVC_STARTEMPTY\nhono.credentials.svc.startEmpty no false When set to true the server will not try to load credentials from the file specified by the HONO_CREDENTIALS_SVC_FILENAME property during startup. HONO_DEVICE_CONNECTION_SVC_MAXDEVICESPERTENANT\nhono.deviceConnection.svc.maxDevicesPerTenant no 100 The number of devices per tenant for which connection related data is stored. It is an error to set this property to a value \u003c= 0. HONO_REGISTRY_AMQP_BINDADDRESS\nhono.registry.amqp.bindAddress no 127.0.0.1 The IP address of the network interface that the secure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_CERTPATH\nhono.registry.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_REGISTRY_AMQP_KEYPATH.\nAlternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_INSECUREPORT\nhono.registry.amqp.insecurePort no - The insecure port the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS\nhono.registry.amqp.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure AMQP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_INSECUREPORTENABLED\nhono.registry.amqp.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_AMQP_INSECUREPORT or the default AMQP port number (5672) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_KEYPATH\nhono.registry.amqp.keyPath no - 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_REGISTRY_AMQP_CERTPATH. Alternatively, the HONO_REGISTRY_AMQP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_AMQP_KEYSTOREPASSWORD\nhono.registry.amqp.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_AMQP_KEYSTOREPATH\nhono.registry.amqp.keyStorePath no - 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_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_AMQP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_AMQP_NATIVETLSREQUIRED\nhono.registry.amqp.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_REGISTRY_AMQP_PORT\nhono.registry.amqp.port no 5671 The secure port that the server should listen on for AMQP 1.0 connections.\nSee Port Configuration below for details. HONO_REGISTRY_AMQP_SECUREPROTOCOLS\nhono.registry.amqp.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_AMQP_SUPPORTEDCIPHERSUITES\nhono.registry.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_HTTP_TENANTIDPATTERN\nhono.registry.http.tenantIdPattern no ^[a-zA-Z0-9-_\\.]+$ The regular expression to use to validate tenant ID. Please refer to the java pattern documentation. HONO_REGISTRY_HTTP_DEVICEIDPATTERN\nhono.registry.http.deviceIdPattern no ^[a-zA-Z0-9-_\\.:]+$ The regular expression to use to validate device ID. Please refer to the java pattern documentation. HONO_REGISTRY_HTTP_BINDADDRESS\nhono.registry.http.bindAddress no 127.0.0.1 The IP address of the network interface that the secure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_CERTPATH\nhono.registry.http.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_REGISTRY_HTTP_KEYPATH.\nAlternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_INSECUREPORT\nhono.registry.http.insecurePort no - The insecure port the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTBINDADDRESS\nhono.registry.http.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure HTTP port should be bound to.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_INSECUREPORTENABLED\nhono.registry.http.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_HTTP_INSECUREPORT or the default HTTP port number (8080) if not set explicitly.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_KEYPATH\nhono.registry.http.keyPath no - 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_REGISTRY_HTTP_CERTPATH. Alternatively, the HONO_REGISTRY_HTTP_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_REGISTRY_HTTP_KEYSTOREPASSWORD\nhono.registry.http.keyStorePassword no - The password required to read the contents of the key store. HONO_REGISTRY_HTTP_KEYSTOREPATH\nhono.registry.http.keyStorePath no - 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_REGISTRY_HTTP_KEYPATH and HONO_REGISTRY_HTTP_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_REGISTRY_HTTP_MAXPAYLOADSIZE\nhono.registry.http.maxPayloadSize no 16000 The maximum size of an HTTP request body in bytes that is accepted by the registry. HONO_REGISTRY_HTTP_PORT\nhono.registry.http.port no 8443 The secure port that the server should listen on for HTTP requests.\nSee Port Configuration below for details. HONO_REGISTRY_HTTP_SECUREPROTOCOLS\nhono.registry.http.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_REGISTRY_HTTP_SUPPORTEDCIPHERSUITES\nhono.registry.http.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_REGISTRY_REST_TENANTIDPATTERN\nhono.registry.rest.tenantIdPattern no ^[a-zA-Z0-9-_\\.]+$ The regular expression to use to validate tenant ID. Please refer to the java pattern documentation.\nDeprecated Use HONO_REGISTRY_HTTP_TENANTIDPATTERN instead. HONO_REGISTRY_REST_DEVICEIDPATTERN\nhono.registry.rest.deviceIdPattern no ^[a-zA-Z0-9-_\\.:]+$ The regular expression to use to validate device ID. Please refer to the java pattern documentation.\nDeprecated Use HONO_REGISTRY_HTTP_DEVICEIDPATTERN instead. HONO_REGISTRY_REST_BINDADDRESS\nhono.registry.rest.bindAddress no 127.0.0.1 The IP address of the network interface that the secure HTTP port should be bound to.\nSee Port Configuration below for details.\nDeprecated Use HONO_REGISTRY_HTTP_BINDADDRESS instead. HONO_REGISTRY_REST_CERTPATH\nhono.registry.rest.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_REGISTRY_REST_KEYPATH.\nAlternatively, the HONO_REGISTRY_REST_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate.\nDeprecated Use HONO_REGISTRY_HTTP_CERTPATH instead. HONO_REGISTRY_REST_INSECUREPORT\nhono.registry.rest.insecurePort no - The insecure port the server should listen on for HTTP requests.\nSee Port Configuration below for details.\nDeprecated Use HONO_REGISTRY_HTTP_INSECUREPORT instead. HONO_REGISTRY_REST_INSECUREPORTBINDADDRESS\nhono.registry.rest.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure HTTP port should be bound to.\nSee Port Configuration below for details.\nDeprecated Use HONO_REGISTRY_HTTP_INSECUREPORTBINDADDRESS instead. HONO_REGISTRY_REST_INSECUREPORTENABLED\nhono.registry.rest.insecurePortEnabled no false If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_REST_INSECUREPORT or the default HTTP port number (8080) if not set explicitly.\nSee Port Configuration below for details.\nDeprecated Use HONO_REGISTRY_HTTP_INSECUREPORTENABLED instead. HONO_REGISTRY_REST_KEYPATH\nhono.registry.rest.keyPath no - 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_REGISTRY_REST_CERTPATH. Alternatively, the HONO_REGISTRY_REST_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate.\nDeprecated Use HONO_REGISTRY_HTTP_KEYPATH instead. HONO_REGISTRY_REST_KEYSTOREPASSWORD\nhono.registry.rest.keyStorePassword no - The password required to read the contents of the key store.\nDeprecated Use HONO_REGISTRY_HTTP_KEYSTOREPASSWORD instead. HONO_REGISTRY_REST_KEYSTOREPATH\nhono.registry.rest.keyStorePath no - 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_REGISTRY_REST_KEYPATH and HONO_REGISTRY_REST_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively.\nDeprecated Use HONO_REGISTRY_HTTP_KEYSTOREPATH instead. HONO_REGISTRY_REST_PORT\nhono.registry.rest.port no 8443 The secure port that the server should listen on for HTTP requests.\nSee Port Configuration below for details.\nDeprecated Use HONO_REGISTRY_HTTP_PORT instead. HONO_REGISTRY_SVC_CACHEMAXAGE\nhono.registry.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_REGISTRY_SVC_FILENAME\nhono.registry.svc.filename no /var/lib/hono/device-registry/\ndevice-identities.json The path to the file where the server stores identities of registered devices. Hono tries to read device identities from this file during start-up and writes out all identities to this file periodically if property HONO_REGISTRY_SVC_SAVETOFILE is set to true.\nPlease refer to Device Identities File Format for details regarding the file’s format. HONO_REGISTRY_SVC_MAXDEVICESPERTENANT\nhono.registry.svc.maxDevicesPerTenant no 100 The number of devices that can be registered for each tenant. It is an error to set this property to a value \u003c= 0. HONO_REGISTRY_SVC_MODIFICATIONENABLED\nhono.registry.svc.modificationEnabled no true When set to false the device information contained in the registry cannot be updated nor removed from the registry. HONO_REGISTRY_SVC_RECEIVERLINKCREDIT\nhono.registry.svc.receiverLinkCredit no 100 The number of credits to flow to a client connecting to the Device Registration endpoint. HONO_REGISTRY_SVC_SAVETOFILE\nhono.registry.svc.saveToFile no false When set to true the server will periodically write out the registered device information to the file specified by the HONO_REGISTRY_SVC_FILENAME property. HONO_REGISTRY_SVC_SIGNING_KEYPATH\nhono.registry.svc.signing.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the server should use for signing tokens asserting a device’s registration status. When using this variable, other services that need to validate the tokens issued by this service need to be configured with the corresponding certificate/public key. Alternatively, a symmetric key can be used for signing (and validating) by setting the HONO_REGISTRY_SVC_SIGNING_SHAREDSECRET variable. If none of these variables is set, the server falls back to the key indicated by the HONO_REGISTRY_AMP_KEYPATH variable. If that variable is also not set, startup of the server fails. HONO_REGISTRY_SVC_SIGNING_SHAREDSECRET\nhono.registry.svc.signing.sharedSecret no - A string to derive a symmetric key from that is used for signing tokens asserting a device’s registration status. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the signing key using this variable, other services that need to validate the tokens issued by this service need to be configured with the same key. Alternatively, an asymmetric key pair can be used for signing (and validating) by setting the HONO_REGISTRY_SVC_SIGNING_KEYPATH variable. If none of these variables is set, startup of the server fails. HONO_REGISTRY_SVC_SIGNING_TOKENEXPIRATION\nhono.registry.svc.signing.tokenExpiration no 10 The expiration period to use for the tokens asserting the registration status of devices. HONO_REGISTRY_SVC_STARTEMPTY\nhono.registry.svc.startEmpty no false When set to true the server will not try to load device identities from the file specified by the HONO_REGISTRY_SVC_FILENAME property during startup. HONO_TENANT_SVC_CACHEMAXAGE\nhono.tenant.svc.cacheMaxAge no 180 The maximum period of time (seconds) that information returned by the service’s operations may be cached for. HONO_TENANT_SVC_FILENAME\nhono.tenant.svc.filename no /var/lib/hono/device-registry/\ntenants.json The path to the file where the server stores tenants. Hono tries to read tenants from this file during start-up and writes out all identities to this file periodically if property HONO_TENANT_SVC_SAVETOFILE is set to true.\nPlease refer to Tenants File Format for details regarding the file’s format. HONO_TENANT_SVC_MODIFICATIONENABLED\nhono.tenant.svc.modificationEnabled no true When set to false the tenants contained in the registry cannot be updated nor removed. HONO_TENANT_SVC_RECEIVERLINKCREDIT\nhono.tenant.svc.receiverLinkCredit no 100 The number of credits to flow to a client connecting to the Tenant endpoint. HONO_TENANT_SVC_SAVETOFILE\nhono.tenant.svc.saveToFile no false When set to true the server will periodically write out the registered tenants to the file specified by the HONO_TENANTS_SVC_TENANT_FILENAME property. HONO_TENANT_SVC_STARTEMPTY\nhono.tenant.svc.startEmpty no false When set to true the server will not try to load tenants from the file specified by the HONO_TENANT_SVC_FILENAME property during startup. The variables only need to be set if the default value does not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Monitoring Options Port Configuration The file based Device Registry supports configuration of both an AMQP based endpoint exposing the Tenant, Device Registration and Credentials APIs as well as an HTTP based endpoint providing resources for managing tenants, registration information and credentials as defined by the Registry Management API. Both endpoints can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The registry will fail to start if none of the ports is configured properly.\nThe following sections apply to configuring both the AMQP and the HTTP endpoint. The environment variables to use for configuring the HTTP endpoint are the same as the ones for the AMQP endpoint, substituting _AMQP_ with _HTTP_, e.g. HONO_REGISTRY_HTTP_KEYPATH instead of HONO_REGISTRY_AMQP_KEYPATH.\nSecure Port Only The server needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\nSetting the HONO_REGISTRY_AMQP_KEYSTOREPATH and the HONO_REGISTRY_AMQP_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_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 port (5671 for AMQP and 8443 for HTTP). The port number can also be set explicitly using the HONO_REGISTRY_AMQP_PORT variable.\nThe HONO_REGISTRY_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 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).\nInsecure 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\nexplicitly setting HONO_REGISTRY_AMQP_INSECUREPORT to a valid port number, or by implicitly configuring the default port (5672 for AMQP and 8080 for HTTP) to be used by setting HONO_REGISTRY_AMQP_INSECUREPORTENABLED to true. The server issues a warning on the console if one of the insecure ports is set to the corresponding default secure port.\nThe HONO_REGISTRY_AMQP_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.\nSetting 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).\nDual 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.\nThis 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.\nSince the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS. 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.\nEphemeral Ports Both the secure as well as the insecure port numbers may be explicitly set to 0. The Device Registry will then use arbitrary (unused) port numbers determined by the operating system during startup.\nAuthentication Service Connection Configuration The Device Registry requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.\nThe connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. Since Hono’s Authentication Service does not allow caching of the responses, the cache properties can be ignored.\nIn addition to the standard client configuration properties, following properties may be set for the connection:\nOS Environment Variable\nJava System Property Mandatory Default Description HONO_AUTH_VALIDATION_CERTPATH\nhono.auth.validation.certPath no - The absolute path to the PEM file containing the an X.509 certificate that the service should use for validating tokens issued by the Authentication service. Alternatively, a symmetric key can be used for validating tokens by setting the HONO_AUTH_VALIDATION_SHAREDSECRET variable. If none of these variables is set, startup of the service fails. HONO_AUTH_VALIDATION_SHAREDSECRET\nhono.auth.validation.sharedSecret no - A string to derive a symmetric key from which is used for validating tokens issued by the Authentication service. The key is derived from the string by using the bytes of the String’s UTF8 encoding. When setting the validation key using this variable, the Authentication service must be configured with the same key. Alternatively, an X.509 certificate can be used for validating tokens by setting the HONO_AUTH_VALIDATION_CERTPATH variable. If none of these variables is set, startup of the service fails. HONO_AUTH_SUPPORTEDSASLMECHANISMS\nhono.auth.supportedSaslMechanisms no EXTERNAL, PLAIN A (comma separated) list of the SASL mechanisms that the device registry should offer to clients for authentication. This option may be set to specify only one of EXTERNAL or PLAIN, or to use a different order. Metrics Configuration See Monitoring \u0026 Tracing Admin Guide for details on how to configure the reporting of metrics.\nDevice Identities File Format The Device Registry supports persisting the device identities and their registration information to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/device-identities.json.\nCredentials File Format The Device Registry supports persisting the devices’ credentials to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/credentials.json.\nTenants File Format The Device Registry supports persisting tenants to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/tenants.json.\nConfiguring Gateway Devices The Device Registry supports devices to act on behalf of other devices. This is particularly useful for cases where a device does not connect directly to a Hono protocol adapter but is connected to a gateway component that is usually specific to the device’s communication protocol. It is the gateway component which then connects to a Hono protocol adapter and publishes data on behalf of the device(s). Examples of such a set up include devices using SigFox or LoRa for communication.\nIn these cases the protocol adapter will authenticate the gateway component instead of the device for which it wants to publish data. In order to verify that the gateway is authorized to publish data on behalf of the particular device, the protocol adapter should include the gateway’s device identifier (as determined during the authentication process) in its invocation of the Device Registration API’s assert Device Registration operation.\nThe Device Registry will then do the following:\nVerify that the device exists and is enabled. Verify that the gateway exists and is enabled. Verify that the device’s registration information contains a property called via and that its value is either the gateway’s device identifier or a JSON array which contains the gateway’s device identifier as one of its values. Only if all conditions are met, the Device Registry returns an assertion of the device’s registration status. The protocol adapter can then forward the published data to the AMQP Messaging Network in the same way as for any device that connects directly to the adapter.\nThe example configuration file (located at $HONO/services/device-registry-file/src/test/resources/device-identities.json) includes a device and a corresponding gateway configured in this way.\nMessaging Configuration The Device Registry uses a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to\nsend Device Provisioning Notification event messages to convey provisioning related changes regarding a device, to be received by downstream applications, send notification messages about changes to tenant/device/credentials data, to be processed by other Hono components. For the event messages a connection to a Apache Kafka cluster is used by default, if configured. If more than one kind of messaging is configured, the decision which one to use is done according to the Tenant Configuration.\nFor notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.\nAMQP 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 being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.\nKafka based Messaging Configuration The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.\nThe following table shows the prefixes to be used to individually configure the Kafka clients used by the Device Registry. 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.\nOS Environment Variable Prefix\nJava System Property Prefix Description HONO_KAFKA_EVENT_PRODUCERCONFIG_\nhono.kafka.event.producerConfig. Configures the Kafka producer that publishes event messages. HONO_KAFKA_NOTIFICATION_PRODUCERCONFIG_\nhono.kafka.notification.producerConfig. Configures the Kafka producer that publishes notification messages about changes to tenant/device/credentials data. Google Pub/Sub Messaging Configuration The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.\n",
    "description": "",
    "tags": null,
    "title": "File Based Device Registry Configuration",
    "uri": "/hono/docs/2.7/admin-guide/file-based-device-registry-config/"
  },
  {
    "content": "The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ based gateways to publish control and data messages to Eclipse Hono™’s Telemetry and Event endpoints.\nTip The Kura adapter is supposed to be used with gateways running Kura version 3.x. Gateways running Kura version 4 and later should connect to the MQTT adapter instead.\nInfo The Kura adapter has been removed in Hono 2.0.0. Support for Kura version 4 and later is still available by means of Hono’s standard MQTT adapter.\nAuthentication The Kura adapter by default requires devices (gateways) to authenticate during connection establishment. The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT packet as well as client certificate based authentication as part of a TLS handshake for that purpose.\nThe adapter tries to authenticate the device using these mechanisms in the following order\nClient Certificate The MQTT adapter supports authenticating clients based on TLS cipher suites using a digital signature based key exchange algorithm as described in RFC 5246 (TLS 1.2) and RFC 8446 (TLS 1.3). This requires a client to provide an X.509 certificate containing a public key that can be used for digital signature. The adapter uses the information in the client certificate to verify the device’s identity as described in Client Certificate based Authentication.\nInfo The adapter needs to be configured for TLS in order to support this mechanism.\nUsername/Password The MQTT adapter supports authenticating clients based on credentials provided during MQTT connection establishment. This means that clients need to provide a user and a password field in their MQTT CONNECT packet as defined in MQTT Version 3.1.1, Section 3.1 when connecting to the MQTT adapter. The username provided in the user field must match the pattern auth-id@tenant, e.g. sensor1@DEFAULT_TENANT.\nThe adapter extracts the auth-id, tenant and password from the CONNECT packet and verifies them using the credentials that the configured Credentials service has on record for the client as described in Username/Password based Authentication. If the credentials match, the client has been authenticated successfully and the connection is being established.\nInfo There is a subtle difference between the device identifier (device-id) and the auth-id a device uses for authentication. See Device Identity for a discussion of the concepts.\nResource Limit Checks The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.\nConnection Limits The adapter rejects a client’s connection attempt with return code 0x05, indicating Connection Refused: not authorized, if\nthe maximum number of connections per protocol adapter instance is reached, or if the maximum number of simultaneously connected devices for the tenant is reached. Please refer to resource-limits for details.\nConnection Duration Limits The adapter rejects a client’s connection attempt with return code 0x05, indicating Connection Refused: not authorized, if the connection duration limit that has been configured for the client’s tenant is exceeded.\nMessage Limits The adapter\ndiscards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and rejects any AMQP 1.0 message containing a command sent by a north bound application if the message limit that has been configured for the device’s tenant is exceeded.\nConnection Events The adapter can emit Connection Events for client connections being established and/or terminated. Please refer to the common configuration options for details regarding how to enable this behavior.\nThe adapter includes the client identifier from the client’s MQTT CONNECT packet as the Connection Event’s remote-id.\nPublishing Data Once the gateway has established a connection to the Kura adapter, all control and data messages published by applications running on the gateway are sent to the adapter and mapped to Hono’s Telemetry and Event API endpoints as follows:\nThe adapter treats all messages that are published to a topic starting with the configured HONO_KURA_CONTROL_PREFIX as control messages. All other messages are considered to be data messages. control messages with QoS 0 are forwarded to Hono’s telemetry endpoint whereas messages with QoS 1 are forwarded to the event endpoint. The corresponding messages that are sent downstream have a content type of application/vnd.eclipse.kura-control. data messages with QoS 0 are forwarded to the telemetry endpoint whereas messages with QoS 1 are forwarded to the event endpoint. The corresponding messages that are sent downstream have a content type of application/vnd.eclipse.kura-data. Downstream Meta Data The adapter includes the following meta data in messages being sent downstream:\nName Location Type Description device_id application string The identifier of the device that the message originates from. orig_adapter application string Contains the adapter’s type name which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The Kura adapter’s type name is hono-kura-mqtt. orig_address application string Contains the name of the MQTT topic that the Kura gateway has originally published the data to. The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:\nIf the message already contains a non-empty property of the same name, the value if unchanged. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used. Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.\nEvent Message Time-to-live Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.\nIn most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.\nIn order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the default ttl and max-ttl values configured for a tenant/device as described in the Tenant API.\nTenant specific Configuration The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-kura-mqtt. The following properties are (currently) supported:\nName Type Default Value Description enabled boolean true If set to false the adapter will reject all data from devices belonging to the tenant. ",
    "description": "",
    "tags": null,
    "title": "Kura Adapter",
    "uri": "/hono/docs/2.7/user-guide/kura-adapter/"
  },
  {
    "content": "The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ 3 based gateways to access Eclipse Hono™’s south bound Telemetry, Event and Command \u0026 Control APIs.\nThe adapter is implemented as a Spring Boot application. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.\nInfo The Kura adapter has been removed in Hono 2.0.0. Support for Kura version 4 and later is still available by means of Hono’s standard MQTT adapter.\nService Configuration The following table provides an overview of the configuration variables and corresponding system properties for configuring the MQTT adapter.\nOS Environment Variable\nJava System Property Mandatory Default Value Description HONO_APP_MAXINSTANCES\nhono.app.maxInstances no #CPU cores The number of verticle instances to deploy. If not set, one verticle per processor core is deployed. HONO_KURA_AUTHENTICATIONREQUIRED\nhono.kura.authenticationRequired no true If set to true the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured Credentials Service. Devices that have failed to authenticate are not allowed to publish any data. HONO_KURA_BINDADDRESS\nhono.kura.bindAddress no 127.0.0.1 The IP address of the network interface that the secure port should be bound to.\nSee Port Configuration below for details. HONO_KURA_CERTPATH\nhono.kura.certPath no - The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_KURA_KEYPATH.\nAlternatively, the HONO_KURA_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_KURA_CONTROLPREFIX\nhono.kura.controlPrefix no $EDC The topic.control-prefix to use for determining if a message published by a Kura gateway is a control message. All messages published to a topic that does not start with this prefix are considered data messages. HONO_KURA_CTRLMSGCONTENTTYPE\nhono.kura.ctrlMsgContentType no application/vnd.eclipse.kura-control The content type to set on AMQP messages created from Kura control messages. HONO_KURA_DATAMSGCONTENTTYPE\nhono.kura.dataMsgContentType no application/vnd.eclipse.kura-data The content type to set on AMQP messages created from Kura data messages. HONO_KURA_DEFAULTSENABLED\nhono.kura.defaultsEnabled no true If set to true the protocol adapter uses default values registered for a device and/or its tenant to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds such default values as Kafka record headers or AMQP 1.0 message (application) properties before the message is sent downstream. HONO_KURA_INSECUREPORT\nhono.kura.insecurePort no - The insecure port the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_KURA_INSECUREPORTBINDADDRESS\nhono.kura.insecurePortBindAddress no 127.0.0.1 The IP address of the network interface that the insecure port should be bound to.\nSee Port Configuration below for details. HONO_KURA_INSECUREPORTENABLED\nhono.kura.insecurePortEnabled no false If set to true the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via HONO_KURA_INSECUREPORT or the default MQTT port number (1883) if not set explicitly.\nSee Port Configuration below for details. HONO_KURA_KEYPATH\nhono.kura.keyPath no - The absolute path to the (PKCS8) PEM file containing the private key that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with HONO_KURA_CERTPATH. Alternatively, the HONO_KURA_KEYSTOREPATH option can be used to configure a key store containing both the key as well as the certificate. HONO_KURA_KEYSTOREPASSWORD\nhono.kura.keyStorePassword no - The password required to read the contents of the key store. HONO_KURA_KEYSTOREPATH\nhono.kura.keyStorePath no - The absolute path to the Java key store containing the private key and certificate that the protocol adapter should use for authenticating to clients. Either this option or the HONO_KURA_KEYPATH and HONO_KURA_CERTPATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_KURA_SNI\nhono.kura.sni no false Set whether the server supports Server Name Indication. By default, the server will not support SNI and the option is false. However, if set to true then the key store format , HONO_KURA_KEYSTOREPATH, should be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. HONO_MQTT_MAXCONNECTIONS\nhono.mqtt.maxConnections no 0 The maximum number of concurrent connections that the protocol adapter should accept. If not set (or set to 0), the protocol adapter determines a reasonable value based on the available resources like memory and CPU. HONO_KURA_MAXPAYLOADSIZE\nhono.kura.maxPayloadSize no 2048 The maximum allowed size of an incoming MQTT message’s payload in bytes. When a client sends a message with a larger payload, the message is discarded and the connection to the client gets closed. HONO_KURA_NATIVETLSREQUIRED\nhono.kura.nativeTlsRequired no false The 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 true, the server will fail to start at all in this case. HONO_KURA_PORT\nhono.kura.port no 8883 The secure port that the protocol adapter should listen on.\nSee Port Configuration below for details. HONO_KURA_SECUREPROTOCOLS\nhono.kura.secureProtocols no TLSv1.3,TLSv1.2 A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. HONO_AMQP_SUPPORTEDCIPHERSUITES\nhono.amqp.supportedCipherSuites no - A (comma separated) list of names of cipher suites (in order of preference) that the adapter may use in TLS sessions with devices. Please refer to JSSE Cipher Suite Names for a list of supported names. HONO_KURA_TENANTIDLETIMEOUT\nhono.kura.tenantIdleTimeout no PT0S The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. 2h for 2 hours. See the java.time.Duration documentation for an explanation of the format. The leading PT can be omitted if only specifying hours, minutes or seconds. The value 0s (or PT0S) disables the timeout. HONO_KURA_SENDMESSAGETODEVICETIMEOUT\nhono.kura.sendMessageToDeviceTimeout no 1000 The amount of time (milliseconds) after which the sending of a command to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. The variables only need to be set if the default values do not match your environment.\nIn addition to the options described in the table above, this component supports the following standard configuration options:\nCommon Java VM Options Common vert.x Options Common Protocol Adapter Options Monitoring Options Port Configuration The Kura protocol adapter can be configured to listen for connections on\na secure port only (default) or an insecure port only or both a secure and an insecure port (dual port configuration) The Kura protocol adapter will fail to start if none of the ports is configured properly.\nSecure Port Only The protocol adapter needs to be configured with a private key and certificate in order to open a TLS secured port.\nThere are two alternative ways for doing so:\neither setting the HONO_KURA_KEYSTOREPATH and the HONO_KURA_KEYSTOREPASSWORD variables in order to load the key \u0026 certificate from a password protected key store, or setting the HONO_KURA_KEYPATH and HONO_KURA_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 MQTT port 8883. The port number can also be set explicitly using the HONO_KURA_PORT variable.\nThe HONO_KURA_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).\nInsecure 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\nexplicitly setting HONO_KURA_INSECUREPORT to a valid port number, or by implicitly configuring the default MQTT port (1883) by simply setting HONO_KURA_INSECUREPORTENABLED to true. The protocol adapter issues a warning on the console if HONO_KURA_INSECUREPORT is set to the default secure MQTT port (8883).\nThe HONO_KURA_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.\nSetting 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).\nDual 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.\nEphemeral 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.\n",
    "description": "",
    "tags": null,
    "title": "Kura Adapter Configuration",
    "uri": "/hono/docs/2.7/admin-guide/kura-adapter-config/"
  },
  {
    "content": "",
    "description": "",
    "tags": null,
    "title": "Tags",
    "uri": "/hono/docs/2.7/tags/"
  }
]