Versions Type Operating system Requirements Dependencies Configuration Local log file Licenses Changelog

MQTT 5 broker (EMQX)

The EMQX MQTT broker component (aws.greengrass.clientdevices.mqtt.EMQX) handles MQTT messages between client devices and a Greengrass core device. This component provides a modified version of the EMQX MQTT 5.0 broker. Deploy this MQTT broker to use MQTT 5 features in communication between client devices and a core device. For more information about how to choose an MQTT broker, see Choose an MQTT broker.

This broker implements the MQTT 5.0 protocol. It includes support for session and message expiration intervals, user properties, shared subscriptions, topic aliases, and more. MQTT 5 is backwards compatible with MQTT 3.1.1, so if you run the Moquette MQTT 3.1.1 broker, you can replace it with the EMQX MQTT 5 broker, and client devices can continue to connect and operate as usual.

Note

Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see Interact with local IoT devices.

Versions

This component has the following versions:

2.0.x
1.2.x
1.1.x
1.0.x

Type

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

For more information, see Component types.

Operating system

This component can be installed on core devices that run the following operating systems:

Linux
Windows

Requirements

This component has the following requirements:

The core device must be able to accept connections on the port where the MQTT broker operates. This component runs the MQTT broker on port 8883 by default. You can specify a different port when you configure this component.

If you specify a different port, and you use the MQTT bridge component to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.

If you specify a different port, and you use the IP detector component to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.
On Linux core devices, Docker installed and configured on the core device:
- Docker Engine 1.9.1 or later installed on the Greengrass core device. Version 20.10 is the latest version that is verified to work with the AWS IoT Greengrass Core software. You must install Docker directly on the core device before you deploy components that run Docker containers.
- The Docker daemon started and running on the core device before you deploy this component.
- The system user that runs this component must have root or administrator permissions. Alternatively, you can run this component as a system user in the docker group and configure this component's requiresPrivileges option to false to run the EQMX MQTT broker without privileges.
The EMQX MQTT broker component is supported to run in a VPC.
The EMQX MQTT broker component is not supported on the armv7 platform.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.0.1

The following table lists the dependencies for version 2.0.1 of this component.

Dependency	Compatible versions	Dependency type
Client device auth	>=2.2.0 <2.6.0	Hard

2.0.0

The following table lists the dependencies for version 2.0.0 of this component.

Dependency	Compatible versions	Dependency type
Client device auth	>=2.2.0 <2.5.0	Hard

1.2.2 – 1.2.3

The following table lists the dependencies for versions 1.2.2 to 1.2.3 of this component.

Dependency	Compatible versions	Dependency type
Client device auth	>=2.2.0 <2.5.0	Hard

1.2.0 and 1.2.1

The following table lists the dependencies for versions 1.2.0 and 1.2.1 of this component.

Dependency	Compatible versions	Dependency type
Client device auth	>=2.2.0 <2.4.0	Hard

1.0.0 and 1.1.0

The following table lists the dependencies for versions 1.0.0 and 1.1.0 of this component.

Dependency	Compatible versions	Dependency type
Client device auth	>=2.2.0 <2.3.0	Hard

For more information about component dependencies, see the component recipe reference.

Configuration

2.0.0 - 2.0.1

This component provides the following configuration parameters that you can customize when you deploy the component.

Important

If you use version 2 of the MQTT 5 broker (EMQX) component, you must update your configuration file. Version 1 configuration files do not work with version 2.

emqxConfig

(Optional) The EMQX MQTT broker configuration to use. You can set EMQX configuration options in this component.

When you use the EMQX broker, Greengrass uses a default configuration. This configuration is used unless you modify it using this field.

Modifying the following configuration settings causes the EMQX broker component to restart. Other configuration changes apply without restarting the component.

emqxConfig/cluster
emqxConfig/node
emqxConfig/rpc

Note

aws.greengrass.clientdevices.mqtt.EMQX allows you to configure security-sensitive options. These include TLS settings, authentication, and authorization providers. We recommended the default configuration that uses mutual TLS authentication and the Greengrass client device auth provider.

Example: Default configuration

The following example shows the defaults set for the MQTT 5 (EMQX) broker. You can override these settings using the emqxConfig configuration setting.


{
  "authorization": {
    "no_match": "deny",
    "sources": []
  },
  "node": {
    "cookie": "<placeholder>"
  }, 
  "listeners": {
     "ssl": {
       "default": {
         "ssl_options": {
           "keyfile": "{work:path}\\data\\key.pem",
           "certfile": "{work:path}\\data\\cert.pem",
           "cacertfile": null,
           "verify": "verify_peer",
           "versions": ["tlsv1.3", "tlsv1.2"],
           "fail_if_no_peer_cert": true
         }
       }
     },
     "tcp": {
       "default": {
         "enabled": false
       }
     },
     "ws": {
       "default": {
         "enabled": false
       }
     },
     "wss": {
       "default": {
         "enabled": false
       }
     }
  },
  "plugins": {
    "states": [{"name_vsn": "gg-1.0.0", "enable": true}],
    "install_dir": "plugins"
  }
}

authMode

(Optional) Sets the authorization provider for the broker. Can be one of the following values:

enabled – (Default) Use the Greengrass authentication and authorization provider.
bypass_on_failure – Use the Greengrass authentication provider, then use any remaining authentication providers in the EMQX provider chain if Greengrass denies either authentication or authorization.
bypass – The Greengrass provider is disabled. Authentication and authorization is handled by the EMQX provider chain.

requiresPrivilege

(Optional) On Linux core devices, you can specify to run the EMQX MQTT broker without root or administrator privileges. If you set this option to false, the system user that runs this component must be a member of the docker group.

Default: true

startupTimeoutSeconds

(Optional) The maximum of time in seconds for the EMQX MQTT broker to start. The component's state changes to BROKEN if it exceeds this timeout.

Default: 90

ipcTimeoutSeconds

(Optional) The maximum of time in seconds for the component to wait for the Greengrass nucleus to respond to interprocess communication (IPC) requests. Increase this number if this component reports timeout errors when it checks if a client device is authorized.

Default: 5

crtLogLevel

(Optional) The log level for the AWS Common Runtime (CRT) library.

Defaults to the EMQX MQTT broker log level (log.level in emqx).

restartIdentifier

(Optional) Configure this option to restart the EMQX MQTT broker. When this configuration value changes, this component restarts the MQTT broker. You can use this option to force client devices to disconnect.

dockerOptions

(Optional) Configure this option only on Linux operating systems to add parameters to the Docker command line. For example, to map additional ports, use the -p Docker parameter:


"-p 1883:1883"

Example: Updating a v1.x configuration file to v2.x

The following example shows the changes necessary to update a v1.x configuration file to version 2.x.

The version 1.x configuration file:


{
    "emqx": {
        "listener.ssl.external": "443",
        "listener.ssl.external.max_connections": "1024000",
        "listener.ssl.external.max_conn_rate": "500",
        "listener.ssl.external.rate_limit": "50KB,5s",
        "listener.ssl.external.handshake_timeout": "15s",
        "log.level": "warning"
    },
    "mergeConfigurationFiles": {
        "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
    }
}

The equivalent configuration file for v2:


{
    "emqxConfig": {
        "listeners": {
            "ssl": {
                "default": {
                   "bind": "8883",
                   "max_connections": "1024000",
                   "max_conn_rate": "500",
                   "handshake_timeout": "15s"
                }
            }
        },
        "log": {
            "console": {
              "enable": true,
              "level": "warning"
            }
        }
    },
    "authMode": "enabled"
}

There is no equivalent to the listener.ssl.external.rate_limit configuration entry. The use_greengrass_managed_certificates configuration option has been removed.

Example: Set a new port for the broker

The following example changes the port where the MQTT broker operates from the default 8883 to port 1234. If you are using Linux, include the dockerOptions field.


{
  "emqxConfig": {
    "listeners": {
      "ssl": {
        "default": {
          "bind": 1234
        }
      }
    }
  },
  "dockerOptions": "-p 1234:1234"
}

Example: Adjust the MQTT broker's log level

The following example changes the MQTT broker's log level to debug. You can choose from the following log levels:

debug
info
notice
warning
error
critical
alert
emergency

The default log level is warning.


{
  "emqxConfig": {
    "log": {
      "console": {
         "level": "debug"
      }
    }
  }
}

Example: Enable the EMQX dashboard

The following example enables the EMQX dashboard so that you can monitor and manage your broker. If you are using Linux, include the dockerOptions field.


{
  "emqxConfig": {
    "dashboard": {
      "listeners": {
        "http": {
          "bind": 18083
        }
      }
    }
  },
  "dockerOptions": "-p 18083:18083"
}

1.0.0 - 1.2.2

This component provides the following configuration parameters that you can customize when you deploy the component.

emqx

(Optional) The EMQX MQTT broker configuration to use. You can configure a subset of EMQX configuration options in this component.

This object contains the following information:

listener.ssl.external

(Optional) The port where the MQTT broker operates.

Note

If you specify a different port, and you use the MQTT bridge component to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.

If you specify a different port, and you use the IP detector component to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.

Default: 8883

listener.ssl.external.max_connections

(Optional) The maximum number of concurrent connections that the MQTT broker supports.

Default: 1024000

listener.ssl.external.max_conn_rate

(Optional) The maximum number of new connections per second the MQTT broker can receive.

Default: 500

listener.ssl.external.rate_limit

(Optional) The bandwidth limit for all connections to the MQTT broker. Specify the bandwidth and duration for that bandwidth separated by a comma (,) in the following format: bandwidth,duration. For example, you can specify 50KB,5s to limit the MQTT broker to 50 kilobytes (KB) of data every 5 seconds.

listener.ssl.external.handshake_timeout

(Optional) The amount of time that the MQTT broker waits to finish authenticating a new connection.

Default: 15s

mqtt.max_packet_size

(Optional) The maximum size of an MQTT message.

Default: 268435455 (256 MB minus 1)

log.level

(Optional) The log level for the MQTT broker. Choose from the following options:

debug
info
notice
warning
error
critical
alert
emergency

The default log level is warning.

requiresPrivilege

Default: true

startupTimeoutSeconds

(Optional) The maximum of time in seconds for the EMQX MQTT broker to start. The component's state changes to BROKEN if it exceeds this timeout.

Default: 90

ipcTimeoutSeconds

Default: 5

crtLogLevel

(Optional) The log level for the AWS Common Runtime (CRT) library.

Defaults to the EMQX MQTT broker log level (log.level in emqx).

restartIdentifier

dockerOptions

(Optional) Configure this option only on Linux operating systems to add parameters to the Docker command line. For example, to map additional ports, use the -p Docker parameter:


"-p 1883:1883"

mergeConfigurationFiles

(Optional) Configure this option to add to or override the defaults in the specified EMQX configuration files. For information about the configuration files and their formats, see Configuration in the EMQX 4.0 Documentation. The values that you specify are appended to the configuration file.

The following example updates the etc/emqx.conf file.


"mergeConfigurationFiles": {
    "etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},

In addition to the configuration files supported by EMQX, Greengrass supports a file that configures the Greengrass auth plugin for EMQX called etc/plugins/aws_greengrass_emqx_auth.conf. There are two supported options, auth_mode and use_greengrass_managed_certificates. To use another auth provider, set the auth_mode option to one of the following:

enabled – (Default) Use the Greengrass authentication and authorization provider.
bypass_on_failure – Use the Greengrass authentication provider, then use any remaining authentication providers in the EMQX provider chain if Greengrass denies either authentication or authorization.
bypass – The Greengrass provider is disabled. Authentication and authorization is then handled by the EMQX provider chain.

If the use_greengrass_managed_certificates is true, this option indicates that Greengrass manages the broker TLS certificates. If false, it indicates that you provide the certificates through another source.

The following example updates the defaults in the etc/plugins/aws_greengrass_emqx_auth.conf configuration file.


"mergeConfigurationFiles": {
    "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
  },

Note

aws.greengrass.clientdevices.mqtt.EMQX allows you to configure security-sensitive options. These include TLS settings, authentication, and authorization providers. The recommended configuration is the default configuration that uses mutual TLS authentication and the Greengrass Client Device Auth provider.

replaceConfigurationFiles

(Optional) Configure this option to replace the specified EMQX configuration files. The values that you specify replace the entire existing configuration file. You can't specify the etc/emqx.conf file in this section. You must use mergeConfigurationFile to modify etc/emqx.conf.

Example: Configuration merge update

The following example configuration specifies to operate the MQTT broker on port 443.


{
  "emqx": {
    "listener.ssl.external": "443",
    "listener.ssl.external.max_connections": "1024000",
    "listener.ssl.external.max_conn_rate": "500",
    "listener.ssl.external.rate_limit": "50KB,5s",
    "listener.ssl.external.handshake_timeout": "15s",
    "log.level": "warning"
  },
  "requiresPrivilege": "true",
  "startupTimeoutSeconds": "90",
  "ipcTimeoutSeconds": "5"
}

Local log file

This component uses the following log file.

To view this component's logs

Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.
Linux
```
sudo tail -f /greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
```
Windows (PowerShell)
```
Get-Content C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log -Tail 10 -Wait
```

Licenses

On Windows operating systems, this software includes code distributed under the Microsoft Software License Terms - Microsoft Visual Studio Community 2022. By downloading this software, you agree to that code's license terms.

This component is released under the Greengrass Core Software License Agreement.

Changelog

The following table describes the changes in each version of the component.

v2.x

Version	Changes
2.0.1	Version updated for client device auth version 2.5.0 release.
2.0.0	This version of the MQTT 5 broker (EMQX) expects different configuration parameters than version 1.x. If you use a non-default configuration for version 1.x, you must update the component's configuration for 2.x. For more information, see Configuration. New features Upgrades the MQTT broker to EMQX 5.1.1. Enables broker configuration changes without restarting the component. Updates Adds a new `emqxConfig` configuration field that replaces the `emqx`, `mergeConfigurationFiles`, and `replaceConfigurationFiles` configuration fields.

Version

Changes

2.0.1

Version updated for client device auth version 2.5.0 release.

2.0.0

This version of the MQTT 5 broker (EMQX) expects different configuration parameters than version 1.x. If you use a non-default configuration for version 1.x, you must update the component's configuration for 2.x. For more information, see Configuration.

New features

Upgrades the MQTT broker to EMQX 5.1.1.
Enables broker configuration changes without restarting the component.

Updates

Adds a new emqxConfig configuration field that replaces the emqx, mergeConfigurationFiles, and replaceConfigurationFiles configuration fields.

v1.x

Version	Changes
1.2.3	Bug fixes and improvements Fixes an issue where clients couldn't interact with EMQX after previously authenticating by disconnecting and reauthenticating the client.
1.2.2	Version updated for client device auth version 2.4.0 release.
1.2.1	Bug fixes and improvements Fixes an issue where the component won't startup on Windows if Visual C++ Redistributable is not already present. Updates EMQX to version 4.4.14.
1.2.0	Adds support for certificate chains.
1.1.0	New features Adds support for EMQX configurations including broker options and plug-ins. Bug fixes and improvements Updates EMQX to version 4.4.9.
1.0.1	Fixes an issue during the TLS handshake which results in some MQTT clients failing to connect.
1.0.0	Initial version.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

MQTT 3.1.1 broker (Moquette)

Nucleus telemetry emitter