# Inspecting and managing sessions

## Inspecting sessions

VerneMQ comes with powerful tools for inspecting the state of MQTT sessions. To list current MQTT sessions simply invoke `vmq-admin session show`:

```
$ vmq-admin session show
+---------+---------+----------+---------+---------+---------+
|client_id|is_online|mountpoint|peer_host|peer_port|  user   |
+---------+---------+----------+---------+---------+---------+
| client2 |  true   |          |127.0.0.1|  37098  |undefined|
| client1 |  true   |          |127.0.0.1|  37094  |undefined|
+---------+---------+----------+---------+---------+---------+
```

To see detailed information about the command see `vmq-admin session show --help`.

The command is able to show a lot of different information about a client, for example the client id, the peer host and port if the client is online or offline and much more, see `vmq-admin session show --help` for details. Further the information can also be used to filter information which is very helpful when wanting to narrow down the information to a single client.

A sample query which lists only the node where the client session exists and if the client is online would look like the following:

```
$ vmq-admin session show --node --is_online --client_id=client1
+---------+--------------+
|is_online|     node     |
+---------+--------------+
|  true   |dev2@127.0.0.1|
+---------+--------------+
```

{% hint style="success" %}
Note, by default a maximum of 100 rows are returned from each node in the cluster. This is a mechanism to protect the cluster from overload as there can be millions of MQTT sessions and resulting rows. Use `--limit=<RowLimit>` to override the default value.
{% endhint %}

### More examples

Listing the clients and the subscriptions one can do the following:

```
$ vmq-admin session show --topic --client_id
+---------+----------------+
|client_id|     topic      |
+---------+----------------+
| client2 |some/other/topic|
| client1 |some/other/topic|
| client1 |   some/topic   |
+---------+----------------+
```

And to list only the clients subscribed to the topic `some/topic`:

```
$ vmq-admin session show --topic --client_id --topic=some/topic
+---------+----------+
|client_id|  topic   |
+---------+----------+
| client1 |some/topic|
+---------+----------+
```

To figure out when the queue for a persisted session (clean\_session=false) was created and when the client last connected one can use the `--queue_started_at` and `--session_started_at` to list the POSIX timestamps (in microseconds):

```
$ vmq-admin session show --client_id=client1 --queue_started_at --session_started_at
+----------------+------------------+
|queue_started_at|session_started_at|
+----------------+------------------+
| 1549379963575  |  1549379974905   |
+----------------+------------------+
```

Besides the examples above it is also possible to inspect the number of online or offline messages as well as their payloads and much more. See `vmq-admin session show --help` for an exhaustive list of all the available options.

## Managing sessions

VerneMQ also supports disconnecting clients and reauthorizing client subscriptions. To disconnect a client and cleanup store messages and remove subscriptions one can invoke:

```
$ vmq-admin session disconnect client-id=client1 --cleanup
```

See `vmq-admin session disconnect --help` for more options and details.

To reauthorize subscriptions for a client issue the following command:

```
$ vmq-admin session reauthorize username=username client-id=client1
Unchanged
```

This works by reapplying the logic in any installed `auth_on_subscribe` or `auth_on_subscribe_m5` plugin hooks to check the validity of the existing topics and removing those that are no longer allowed. In the example above the reauthorization of the client subscriptions resulted in no changes.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vernemq.com/1.9.0/administration/managing-sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.