| Line 1: |
Line 1: |
| − | ==Summary==
| + | {{Template: Networking_rutos_manual_mqtt |
| − | | + | <!------------------------DEVICE-----------------------> |
| − | '''MQTT (MQ Telemetry Transport or Message Queue Telemetry Transport)''' is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based "lightweight" messaging protocol for use on top of the TCP/IP protocol. It is designed to send short messages from one client ('''publisher''') to another ('''subscriber''') through '''brokers''', which are responsible for message delivery to the end point. RUT routers support this functionality via an open source Mosquitto broker. The messages are sent this way: a client ('''subscriber''') subscribes to a topic(s); a publisher posts a message to that specific topic(s). The '''broker''' then checks who is subscribed to that particular topic(s) and transmits data from the publisher to the subscriber. This chapter is a summary of the MQTT function in RUT routers.
| + | | name = RUT900 |
| − | | + | | series = RUT9 |
| − | For in-depth MQTT configuration examples, refer to this page: '''[[Monitoring via MQTT]]'''
| + | }} |
| − | ==MQTT Broker==
| |
| − | | |
| − | The '''Broker''' will “listen” for connections on the specified Local port. In order to accept connections from WAN, you also need to check Enable Remote Access.
| |
| − | | |
| − | [[Image:Services mqtt broker.PNG]]
| |
| − | | |
| − | <table class="nd-mantable">
| |
| − | <tr>
| |
| − | <th>field name</th>
| |
| − | <th>value</th>
| |
| − | <th>description</th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>Enable</td>
| |
| − | <td>yes {{!}} no; Default: '''no'''</td>
| |
| − | <td>Toggles MQTT Broker ON or OFF</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>Local Port</td>
| |
| − | <td>integer [0..65535]; Default: " "</td>
| |
| − | <td>Specifies the local port that the MQTT broker will listen to</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>Enable Remote Access</td>
| |
| − | <td>yes {{!}} no; Default: '''no'''</td>
| |
| − | <td>If enabled, MQTT Broker will be reachable by remote user (from WAN)</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | ===Security===
| |
| − | ---- | |
| − | The MQTT '''Security''' tab is used to establish MQTT connection security via TLS/SSL.
| |
| − | | |
| − | [[Image:Services mqtt broker settings security.PNG]]
| |
| − | | |
| − | <table class="nd-mantable">
| |
| − | <tr>
| |
| − | <th>field name</th>
| |
| − | <th>value</th>
| |
| − | <th>description</th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>Use TLS/SSL</td>
| |
| − | <td>yes {{!}} no; Default: '''no'''</td>
| |
| − | <td>Toggles the use of TLS/SSL certificates ON or OFF</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>CA File</td>
| |
| − | <td>.ca file; Default: " "</td>
| |
| − | <td>'''Certificate authority''' is an entity that issues digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>CERT File</td>
| |
| − | <td>.crt file; Default: " "</td>
| |
| − | <td>Certificate file is a type of digital certificate that is used by client systems to make authenticated requests to a remote server. Client certificates play a key role in many mutual authentication designs, providing strong assurances of a requester's identity</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>Key File</td>
| |
| − | <td>.key file; Default: " "</td>
| |
| − | <td>Specifies the local port that the MQTT broker will listen to</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>TLS version</td>
| |
| − | <td>tlsv1 {{!}} tlsv1.1 {{!}} tlsv1.2 {{!}} Support all; Default: '''Support all'''</td>
| |
| − | <td>Authenticates a client to a server and establishes precisely who they are</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | ===Bridge===
| |
| − | ---- | |
| − | The MQTT Broker also supports a functionality called '''Bridge'''. An MQTT Bridge is used for the communication between two MQTT Brokers. The window of Bridge parameters is presented below. Some of these are mandatory as they are needed to create a connection: Connection Name, Remote Address and Remote Port. For more information on '''MQTT Bridge''' parameters you can read the official mosquitto.conf manual page.
| |
| − | | |
| − | [[Image:Services mqtt broker settings bridge.PNG]]
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |+
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | FIELD NAME
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | VALUE
| |
| − | ! style="width: 579px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | DESCRIPTION
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Use TLS/SSL
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Toggles MQTT Bridge ON or OFF
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Connection Name
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | string; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Name of the Bridge connection. Although this is used for easier management purposes, this field is mandatory
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Remote Address
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | ip; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Remote Broker’s address
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Remote Port
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | integer [0..65535]; Default: '''1883''' | |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Specifies which port the remote broker uses to listen for connections
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Use Remote TLS/SSL
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Enables the use of TSL/SSL certificates of the remote broker. If this is checked, you will be prompted to upload TLS/SSL certificates. More information can be found in the [[#Security|Security]] section of this chapter | |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Use Remote Bridge Login
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Enables the use of Remote login data. If this is checked, you will be prompted to enter a remote client ID, username and password
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Topic
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | string; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Specifies the names of the Topics that your Broker will subscribe to
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Try Private
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Check if the remote Broker is another instance of a daemon
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Clean Session
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Check to discard session state after connecting or disconnecting
| |
| − | |-
| |
| − | |}
| |
| − | | |
| − | ===Micellaneous===
| |
| − | ----
| |
| − | The last section of MQTT Broker parameters is called '''Miscellaneous'''. It contains parameters that are related to neither Security nor Bridge.
| |
| − | | |
| − | [[Image:Services mqtt broker settings misc.PNG]]
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |+
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | FIELD NAME
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | VALUE
| |
| − | ! style="width: 579px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | DESCRIPTION
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | ACL File
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | .ACL file; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | The contents of this file are used to control client access to topics of the broker
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Password File
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | password file; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | The Password file stores user names and corresponding passwords, used for authentication
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Persistence
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | If enabled, connection, subscription and message data will be written to the disk. Otherwise, the data is stored in the router’s memory only
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Allow Anonymous
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''yes'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | If enabled, the Broker allows anonymous access
| |
| − | |-
| |
| − | |}
| |
| − | | |
| − | ==MQTT Publisher==
| |
| − | | |
| − | An '''MQTT Publisher''' is a client that sends messages to the Broker, who then forwards these messages to the Subscriber.
| |
| − | | |
| − | [[Image:Services mqtt publisher.PNG]]
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |+
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | FIELD NAME
| |
| − | ! style="width: 250px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | VALUE
| |
| − | ! style="width: 579px; border: 1px solid white; border-bottom: 2px solid #0054A6; background: white; color: #0054A6; text-align: left;" | DESCRIPTION
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Enable
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | yes {{!}} no; Default: '''no'''
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Toggles the MQTT Publisher ON or OFF
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Hostname
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | host {{!}} ip; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Broker’s IP address or hostname
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Port
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | integer [0..65535]; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Specifies the port used for connecting to the Broker
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Username
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | string; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | User name used for authentication when connecting to the Broker
| |
| − | |-
| |
| − | ! style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Password
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | string; Default: " "
| |
| − | | style="border: 1px solid white; border-bottom: 2px solid #E8E8E8; text-align: left; vertical-align: top; background: white;" | Password used for authentication when connecting to the Broker
| |
| − | |-
| |
| − | |}
| |
