Deployment Settings

The Deployment Settings page allows you to view and configure key settings of your EMQX Cloud deployment, including deployment information, cloud details, and MQTT protocol behavior.

This page is available under Deployment Settings in the left navigation panel of your deployment.

Overview

The Deployment Settings page includes two tabs:

• General Settings: View deployment details, billing information, and cloud platform settings.

• MQTT Settings: Configure MQTT parameters, including packet size, shared subscription strategy, session behavior, and flapping detection.

General Settings

The General Settings tab provides an overview of your deployment information and cloud environment, as well as options to manage your plan and billing.

Deployment Info

This section displays basic information about your deployment.

Field	Description
Deployment Name	The name of your deployment. You can edit it directly by clicking the edit icon, or copy it using the copy icon.
Deployment ID	The unique identifier of your deployment. You can copy it using the copy icon when needed, for example, when contacting support or using APIs.
Plan	The current deployment plan, such as Dedicated Flex or Serverless.
EMQX Version	The EMQX version currently running in your deployment.
Tier	The current performance tier, indicating the maximum supported sessions and message throughput (TPS). For supported Dedicated Flex deployments, click Change Tier to modify the capacity. Tier changes are not available for deployments on Oracle Cloud. See Change Deployment Tier for details.
Billing Method	The current billing method (for example, Pay as you go). You can contact EMQ for annual commitment options or custom pricing.
Operation Protection	Indicates whether operation protection is currently enabled or disabled. Operation protection is not available for deployments on Oracle Cloud. See Operation Protection for details.

Tip: Contact EMQ sales for exclusive discounts or dedicated capacity options.

Operation Protection

Operation protection is not available for deployments on Oracle Cloud.

Operation protection guards against accidental deletion, stop, or scaling of a deployment. When enabled, these operations are blocked until protection is manually disabled.

Operation protection is disabled by default when a deployment is created. The system automatically enables it if no write operations have been performed on the deployment for 90 days.

Note

Any operation that changes the deployment's state or configuration (such as renaming, scaling, stopping, or upgrading) resets the 90-day timer. Read-only actions such as viewing metrics, logs, or configuration do not.

To disable operation protection, click Disable next to the Operation Protection field on the General Settings tab.

Cloud Info

This section shows information about the cloud infrastructure where your deployment is hosted.

Field	Description
Cloud Platform	The cloud service provider hosting your deployment, such as AWS, Azure, or Google Cloud.
Region	The geographical region of your cloud instance (for example, N. Virginia (us-east-1)).

Delete Deployment

To permanently remove a deployment, click Delete Deployment at the bottom of the page. Deleting a deployment removes all data and configurations associated with it.

Note

This operation cannot be undone. For more information, see Delete a Deployment.

MQTT Settings

Note

The MQTT Settings tab is available for Dedicated and Dedicated Flex deployments running EMQX 5.10.3 or later. If you do not see this tab, submit a ticket to check availability for your deployment.

The MQTT Settings tab allows you to customize MQTT protocol parameters to suit your application’s requirements. These configurations control how EMQX Cloud handles client sessions, subscriptions, message dispatching, and packet validation.

The deployment must be running to view or modify these settings. Administrators, Project Administrators, and Project Users can modify settings within their authorized scope. Users with read-only access can view the settings but cannot change them. For details, see Subaccount Management.

The settings shown on this tab reflect the deployment's current EMQX configuration.

Basic Settings

Setting	Description
Max Packet Size	Defines the maximum MQTT packet size that EMQX will accept. If a client sends a packet exceeding this limit, EMQX Cloud disconnects the client. Use this setting to prevent excessive payloads that might impact performance.
Shared Subscription Strategy	Determines how EMQX Cloud distributes messages among subscribers in a shared subscription group. Available strategies: random: Sends each message to a randomly selected subscriber. round_robin: Distributes messages evenly among subscribers in order. round_robin_per_group: Performs round-robin dispatching within each shared subscription group. sticky: Keeps dispatching to the same subscriber until that subscriber disconnects. local: Prefers a random subscriber on the local node; if none are available, selects randomly across the cluster. hash_topic: Uses the message’s source topic hash to determine the subscriber. hash_clientid: Uses the sender’s client ID hash to determine the subscriber. This setting helps optimize load balancing and message delivery consistency in clustered environments. For more information about shared subscriptions, see Shared Subscription in EMQX Cloud and Introduction to MQTT 5.0 Shared Subscriptions.
Shared Subscription Initial Sticky Pick	Specifies how the first subscriber is chosen when using the sticky dispatch strategy. Options: random: Selects a random subscriber. local: Prefers a subscriber on the local node; if unavailable, selects randomly across the cluster. hash_clientid: Hashes the publisher’s client ID to select a subscriber. hash_topic: Hashes the publishing topic to select a subscriber. This setting determines the initial load distribution behavior when a shared subscription group becomes active.
Use Peer Certificate as Username	Enables EMQX Cloud to extract the MQTT Username field from the client’s TLS certificate. This is useful for certificate-based authentication. Supported methods: cn: Use the Common Name (CN) field of the certificate. dn: Use the Distinguished Name (DN) field. crt: Use the raw content of the DER or PEM certificate. pem: Convert DER content to PEM format and use as username. md5: Use the MD5 hash of the DER or PEM certificate. Only effective for TLS connections.
Use Peer Certificate as Client ID	Enables EMQX Cloud to derive the Client ID from the client’s TLS certificate. Supported methods are the same as for username: cn, dn, crt, pem, or md5. This option provides a secure and deterministic way to generate client IDs for certificate-based connections.
Client Attributes	Defines how to initialize custom client attributes at connection time. Each attribute can be declared as client_attrs.{NAME}, where {NAME} is the attribute key specified in the set_as_attr configuration field. Note: The attribute name tns is reserved for internal system use and must not be used. Initialized attributes are stored in the client_attrs property and can be used to dynamically render mountpoints, or referenced in authentication and authorization rules. For details on how to configure and use client attributes, see Client Attributes in EMQX.

Session Settings

Setting	Description
Session Expiry Interval	Specifies how long EMQX Cloud retains session data after a client disconnects. Applies only to non–MQTT 5.0 connections. Use this to control how long offline messages or subscriptions are preserved.
Max Inflight	Defines the maximum number of QoS 1 and QoS 2 messages that can be sent simultaneously without acknowledgment. Higher values may improve throughput but increase memory usage.
Max Message Queue Length	Specifies the maximum queue length for messages when a persistent client is disconnected or when the inflight window is full. When the queue reaches this limit, older messages are dropped.
Store QoS 0 Message	Controls whether QoS 0 messages for an offline client are queued while its session remains. When enabled, messages can be queued and delivered when the client resumes the session, if they are still available. When disabled, messages are discarded instead of being added to the queue.

To store offline QoS 0 messages, the client must retain its session after disconnecting. This setting does not change QoS delivery guarantees, control retained messages, or provide disk persistence.

Queued messages consume memory and count toward Max Message Queue Length. Enabling QoS 0 message storage may increase memory usage. Consider the number of offline sessions and the number and size of messages when setting the queue length limit and session retention period. Messages can still be lost when the queue is full or the session expires.

Flapping Detection Settings

Flapping detection identifies clients that disconnect and reconnect abnormally frequently, and temporarily bans them to protect the cluster from excessive load. Flapping detection is always enabled and cannot be turned off; only the thresholds can be adjusted.

Setting	Description
Max Disconnection Count	The maximum number of disconnections allowed for a client within the detection time window. If a client exceeds this count, it is banned for the duration specified in Ban Duration.
Detection Time Window	The length of the time window in which disconnections are counted.
Ban Duration	The duration for which a flapping client ID is banned after the disconnection threshold is exceeded.

Update Configuration

After modifying the required MQTT settings, click Update to save. After the update succeeds, verify that the page shows the configuration you saved.