HiveMQ Control Center v2: Clients
With millions of connected clients, keeping track of specific clients can be a challenge. The HiveMQ Control Center provides tools to list, view, and manage all MQTT clients known to your HiveMQ Platform. Access detailed information about each client, including subscriptions, connection status, TLS, and more. With the Clients view, you can gain deep insights into every client connected to your HiveMQ Platform.
|
Client Sessions in MQTT
Clients that connect to the HiveMQ Platform create a session upon connection.
The client can request to establish a session that persists when the client disconnects.
This allows the client to reconnect and resume its previously established subscriptions.
If the client is connected, the connection status is When a client connects to an MQTT broker, the client subscribes to each topic for which it wants to receive messages from the broker. If the client connects to the MQTT broker with a non-persistent session, the broker does not save any subscription information when the client disconnects. In a non-persistent session, each time the client reconnects to the MQTT broker, the client must resubscribe to each topic of interest. In a persistent session, the HiveMQ broker saves all relevant client information and uses the client ID the client provided during connection establishment to identify the session. For more information, see MQTT Essentials: Understanding Persistent Sessions and Clean Sessions. |
Client Sessions View
The Client Sessions overview of the HiveMQ Control Center provides a consolidated view of all MQTT client sessions on your HiveMQ Platform cluster at a particular point in time.
A summary of the results retrieved, available results, time of retrieval, and the total volume of available results appears at the top of the overview.
| The data on the Client Sessions overview does not update automatically. To reload the data shown, refresh your browser page. |
To prevent extensive searches from impacting the performance of your broker, the maximum number of clients listed on the overview is restricted to 1,000 results. If the available results exceed the 1,000 client limit, a Retrieval Limit Reached notification displays, and only the first 1,000 results are listed.
| To refine your search, use our Client Search functionality to set specific search criteria. To retrieve more than 1,000 search results, use the HiveMQ REST API to create your query. |
| Sorting options and filters that you apply to the Client Sessions overview are not retained when you leave the page. However, you can bookmark the page with your active search filters. Re-opening the bookmark will automatically re-run the client query with your filters. This method can also be used to share specific filtered views. |
The following information is provided for each client session:
| Column | Description |
|---|---|
Client ID |
The unique identifier of the client. |
Connection |
The current connection status of the client. Possible values are Active (connected) or Inactive (disconnected). |
Queue Size |
The total number of QoS 0, 1, and 2 messages in the message queue of the client. |
Username |
The username of the client, if available. |
IP Address |
The IP address of the client. |
Last Status Change |
The timestamp of the last time the client changed its connection status between connected and disconnected. |
Client Search
The Client ID search field on the Client Sessions overview allows you to quickly filter for clients that start with the entered string. To create a search, enter one or more characters and select Search.
Advanced Client Search
The flexible Advanced Search functionality allows you to create detailed queries across the available client session data with customizable filters and conditions. Our Advanced Search feature supports multi-parameter filtering by client ID, username, IP address, connection status, queue size, and recent connection changes. You can also specify the order in which your results are sorted.
Use the Advanced Search interface to access specific client sessions and details.
Advanced Search Filters
One or more of the following Advanced Search filter options can be defined and applied:
| Filter Option | Description |
|---|---|
Client ID |
Filter for client IDs that match various search operators. |
Username |
Filter for client usernames. |
IP Address |
Filter for client IP addresses. |
Queue Size |
Filter for clients with queue sizes smaller or larger than a given amount. |
Last Status Change |
Filter for clients that changed connection status before or after a selected date and time. |
Connection |
Filter for connected (Active) or disconnected (Inactive) clients. |
Client ID Search Operators
The Client ID filter option can be refined with the following operators:
| Filter Operators | Description |
|---|---|
equals |
Filters for a client ID that is an exact match to the given text. |
not equals |
Filters for client IDs that do not match the given text |
contains |
Filters for client IDs that contain the given text. |
starts with |
Filters for client IDs that start with the given text. |
ends with |
Filters for client IDs that end with the given text. |
regular expression |
Filters for client IDs that match the given regular expression |
Advanced Search Sorting Options
The search results can be sorted in Ascending or Descending order based on one of the following criteria:
| Sorting Option | Description |
|---|---|
Client ID |
Sorts alphabetically by client ID. |
Username |
Sorts alphabetically by username. |
IP Address |
Sorts by IP address. |
Queue Size |
Sorts by queue size. |
Last Status Change |
Sorts by the date of the latest connection or disconnection. |
Connection |
Sorts by connection status. |
Client Detail
The Client Detail page displays when you select a client identifier on the Client Sessions overview. The client identifier and the connection status of the client for which details are shown appear at the top of the page, as well as options to copy the client ID, refresh the page content, or disconnect the client from your HiveMQ broker.
The tabs of the Client page provide extensive information about the selected client:
Session Information
The cards on the Session Information tab provide detailed information about the client session of the selected client.
Session
| Entry | Description |
|---|---|
Client ID |
The unique identifier of the MQTT client within the HiveMQ broker. The Client ID can be copied to the clipboard. |
Connected at/Disconnected since |
The date and time when the client last established or lost connection with the broker. |
Session Expires In |
The time in seconds the session will continue to persist since the last page refresh. |
Session Expiry Interval |
The session expiry interval is set for the client. The expiry timer starts when the client disconnects. If the client does not reconnect within the predefined period, the session is invalidated, and the broker deletes all client information, including subscriptions and queued messages. The expiry does not apply while the client is connected. A session expiry interval of '0' means session invalidation at disconnect. This setting is only available for offline clients. |
QoS 1 and QoS 2 Message Queue Size |
The current number of QoS 1 and 2 messages in the message queue of the client. The queue can contain messages that a client with a persistent session receives while offline and messages that an online client has yet to acknowledge. |
Last Will
The Last Will and Testament (LWT) message notifies subscribers when a client disconnects ungracefully. Each client can specify an LWT message when it connects to the broker. The LWT message is a normal MQTT message with a topic, retained flag, QoS, and payload. The broker stores the LWT message until it detects an unexpected disconnection of the client. If the client disconnects abruptly, the broker sends the LWT message to all clients that subscribe to the topic. The broker discards the LWT message if the client disconnects gracefully with a DISCONNECT message.
| Entry | Description |
|---|---|
Will Topic |
The topic on which the Last Will payload is published. |
Will QoS |
The Quality of Service level with which the Last Will message is published. |
Will Retained |
Defines whether the broker processes the last will message as a retained message. |
Will Payload |
The payload of the last will message. |
Connection
MQTT connections are always between an individual client and the broker. Clients never connect directly to each other.
To start a connection, the client sends a CONNECT message to the broker. The broker responds with a CONNACK message and a status code.
Once a connection is established, the broker maintains the connection until the client sends a disconnect command or the connection is lost.
| Entry | Description |
|---|---|
Client IP |
The network IP address of the client. The address can be IPv4 or IPv6. The Client IP can be copied to the clipboard. |
Clean Start |
Shows the type of session the client requested from the broker.
|
Username |
The username the client provides when the MQTT connection is established. |
Password |
The password the client provides when the MQTT connection is established. Permissions can be used to hide this information. |
MQTT Versions |
The version number of the MQTT protocol used for the connection. |
Keep Alive |
The number of seconds the broker permits between when a client finishes sending one MQTT packet and starts to send the next. The broker must disconnect a client that does not send a message or an MQTT PINGREQ packet in one and a half times the stated keep-alive interval. The broker responds with a PINGRESP message to notify the client that the connection is still active. |
Listener |
The type of listener and the address over which the client is connected to the broker. For more information, see HiveMQ MQTT Listeners. |
Connected Node |
The unique identifier of the cluster node to which the client is connected. |
Proxy Protocol
Use of the TCP-based Proxy protocol provides a convenient way to safely transport connection information such as the client address across multiple layers of NAT or TCP proxies.
For more information, see PROXY Protocol.
| Entry | Description |
|---|---|
Source IP/Port |
The source (origin) IP address and port of the proxy. |
Destination IP/Port |
The destination IP address and port of the proxy. |
Additional TLVs |
The Type-length-values (TLVs) key-value pairs that provide optional information such as the SSL X509 client certificate Common Names or the TLS version used by a client that is connected to the proxy. |
TLS
Transport Layer Security (TLS) is a cryptographic protocol that provides a secure connection between the client and the server.
For more information, see TLS.
| Entry | Description |
|---|---|
TLS Version |
The TLS version that is in use. For example, TLSv1.2 or TLSv1.3. |
Cipher Suite |
TLS protocols use algorithms from the cipher suite to create keys and encrypt information. The cipher suite provides an algorithm for the following tasks:
|
x509 Certificate |
The digital certificate used to verify the identity and enable encrypted communication between the broker and client. |
Restrictions
To ensure a trouble-free MQTT communication process, constraints can be configured.
For more information, see Restrictions.
| Entry | Description |
|---|---|
Maximum Bytes Per Second Inbound |
The maximum number of bytes the client can receive per second. |
Maximum Bytes Per Second Outbound |
The maximum number of bytes the client can receive per second. |
Maximum Message Size |
The maximum MQTT message packet size that the client can publish. |
Maximum Message Queue Size |
The maximum number of QoS 1 and QoS 2 messages the broker can queue for the client. |
Drop Strategy for Queued Messages |
Defines how the broker manages QoS 1 and QoS 2 messages when the message queue limit is reached.
|
Subscriptions
The Subscription tab provides detailed information on each standard subscription of the client.
| Column | Description |
|---|---|
Topic Filter |
The string used to match topic names from which the client wants to receive messages. The topic filter can be copied to the clipboard. |
Retain as Published |
A client subscription option that determines whether the retained message flag is delivered to the client.
Retain as Published is an MQTT 5 feature. |
No Local |
A client subscription option that determines whether a client receives its own PUBLISH messages.
No Local is an MQTT 5 feature. |
Retain Handling |
A client subscription option that specifies how retained messages are delivered.
Retain Handling is an MQTT 5 feature. |
Subscription Identifier |
An optional identifier that MQTT clients can use to associate received PUBLISH messages with the corresponding subscriptions. Clients can send a subscription identifier with each SUBSCRIBE message. The identifier is associated with every topic filter in the SUBSCRIBE message. Subscription Identifier is an MQTT 5 feature. |
Quality of Service (QoS) |
Defines the maximum message delivery level the client wants to receive from the broker for a given topic.
|
| To learn more about the subscription options a client can set, see MQTT 5 Subscription Options: A Quick Guide. |
Session Attributes
The Sessions Attributes tab of the Client Detail provides a list of all session attributes associated with the client.
Session attributes are a convenient way to add additional key-value data to the session of an MQTT client.
Each session attribute contains a key and a value.
There are various ways to add session attributes.
For example, session attributes can be added with the HiveMQ Enterprise Security Extension Session Attribute Preprocessor. Session can also be added with custom extensions. For more information, see Add a Session Attribute to a Client.
| Entry | Description |
|---|---|
key |
The key of the session attribute. |
value |
The value of the session attribute. |
Actions |
Click to access details of the session attribute. A dialog box opens to select the encoding of the content. The following options are available:
The content of the session attribute can be downloaded as a file or copied to the clipboard. |