# Sessions

Every connection through ShellHub is a session, and every session is recorded in the list — whether or not the _contents_ were recorded.

![The Sessions page listing active and historical SSH sessions](https://docs.shellhub.io/img/shots/session-list.png)

## What a session tells you

|                  |                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Who              | The authenticated principal — a person or an automation                                                                                     |
| Which device     | The device they reached                                                                                                                     |
| Which unix login | The user they connected as                                                                                                                  |
| When             | Start, and end for a closed session                                                                                                         |
| From where       | The client address, resolved through `SHELLHUB_SSH_PROXY_TRUSTED_IPS` for SSH clients and `SHELLHUB_PROXY_TRUSTED_IPS` for the web terminal |

That “who” is the payoff of the identity model. In a legacy namespace the record could only name the key that was used; here it names the principal the key belongs to. See [How Authorization Works](https://docs.shellhub.io/manage/access-control).

### A red username is worth stopping on

A username shown in red, with a warning triangle, marks a session that **never authenticated**. A record is written when a connection arrives and flipped to authenticated only once the SSH authentication succeeds, so a red row is an attempt that reached the server and got no further.

One is ordinary — a wrong key, a client that gave up. A run of them against one device, or from one address, is the thing this list exists to show you.

## Session details

![A session detail page showing the session flow timeline, details, device, and play recording button](https://docs.shellhub.io/img/shots/session-detail.png)

A session’s own page adds the flow of the connection, the device it reached, and — when there is a recording — the button that replays it. Active sessions can be inspected while they are still running.

## Sessions and authorization

Worth understanding together, because it explains something that otherwise looks like a bug.

**Authorization happens once, when the connection is made.** Revoking an identity, deleting a policy or removing a member does not end a session already running. It was authorized when it started, and it continues until it is closed.

So the sessions list is not only history — for live sessions it is the answer to “who is connected right now”, and the place to look after revoking somebody’s access if you need to be sure they are actually gone.

## Recording

ShellHub can capture what happened in a terminal and play it back. It does this **two** ways, and they answer different questions.

|                             | Browser-local                           | Server-side                                 |
| --------------------------- | --------------------------------------- | ------------------------------------------- |
| Answers                     | What did I do                           | What did anyone do                          |
| Edition                     | **Community**, Cloud, Enterprise        | Cloud and Enterprise                        |
| Where the recording lives   | In the browser that opened the session  | On the server                               |
| Covers                      | Web terminal sessions from that browser | Every session, including native SSH clients |
| Survives clearing site data | No                                      | Yes                                         |
| Available to other members  | No                                      | Yes                                         |

**Browser-local recording is in Community, and it is yours.** The web terminal records the session in the browser and keeps it there: no server storage and nobody else’s eyes. Replay the work you did on a machine last week, or find the step that broke it. It never leaves the browser you made it in, which is the point.

**Server-side recording is Cloud and Enterprise, and it is the namespace’s.** The server makes it, so it covers every session from every client — native `ssh` included, not only the web terminal — and keeps it where the people responsible for the fleet can replay it. That is the one that answers “who touched this device, and what did they do”. It is on from the moment the namespace exists, and [Settings](https://docs.shellhub.io/manage/settings) turns it off; either way the change applies to new sessions, and sessions already running are unaffected.

### Playing one

Every row in the session list carries a **Play** button, and a recorded session repeats it as **Play Recording** on its detail page. Either one opens the player, which replays the terminal in real time — what was typed, what was displayed, and the timing between them:

_A recorded session: nginx fails to start because another process holds port 80_

From there it behaves like a video: play, pause, scrub, and slow it down or speed it up.

### What a recording holds

**Captured:** everything the terminal displayed, everything typed, and terminal resizes.

**Not captured:** file transfer payloads, and forwarded port traffic. A recording will show somebody ran `scp`; it will not show the file’s contents. It will show they opened a forward; it will not show what went through it.

Know that before relying on recordings for an audit requirement.

### Deciding what gets recorded

A recording is a replay of a terminal, so it holds whatever that terminal showed. Two controls decide how much of that exists and who reaches it.

**Recording is a namespace setting, and a new namespace starts with it on.** Turn it off in [Settings](https://docs.shellhub.io/manage/settings) and the server records nothing from then on. Nothing obliges a namespace to record, and a namespace that does not need an audit trail should not.

**Playback is administrator and owner only.** An operator can open a session and read the session list, and still cannot replay one. A recording is not something everybody in the namespace can watch — see [User Roles](https://docs.shellhub.io/manage/team/user-roles). This is about recordings the server holds: a browser-local one is your own data, and plays for you regardless.

## What is not here

**Denial reasons.** A refused connection does not become a session — it was refused before the device was contacted. The reason is not surfaced to the client either. See [Connection Denied](https://docs.shellhub.io/manage/access-control/connection-denied).

**Web endpoint traffic.** A [web endpoint](https://docs.shellhub.io/connect/web-endpoints) is reached by URL, not by an authenticated session, so requests to it do not appear here.

## Where to go next

- [Settings](https://docs.shellhub.io/manage/settings) — Turning recording off.
- [User Roles](https://docs.shellhub.io/manage/team/user-roles) — Who may replay a recording.
- [Connection Denied](https://docs.shellhub.io/manage/access-control/connection-denied) — When a session never happened.