threshold/website/content/docs/common-workflows/manage-sessions.mdx

---
layout: docs
page_title: Manage Sessions
description: How to manage Boundary sessions
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

# Manage Sessions

[Sessions](/boundary/docs/domain-model/sessions) are Boundary resources created when connecting to a [Target](/boundary/docs/domain-model/targets). A target allows Boundary users to define an endpoint with a protocol and default port to establish a session. Unless specified with a `-host-id` flag when establishing a session, Boundary will choose one [Host](/boundary/docs/domain-model/hosts) from the target's [Host Sets](/boundary/docs/domain-model/host-sets) to connect to at random.

In this section, we'll show you the basics of how to start a session, view the session details, and cancel a session in Boundary using the CLI.

We assume you're running Boundary in `dev` mode using the default target resource of `ttcp_1234567890`. We also assume you've authenticated using the CLI. See the output of `boundary dev` for these login values.

## Start a Session

Connecting to a target creates a session in Boundary (via a call to the target to authorize a session for the user). To demonstrate what a session looks like we are going to connect to a `tcp` target with a default port of 22 for SSH access.

```bash
$ boundary connect ssh -target-id ttcp_1234567890 --

Proxy listening information:
    Address:             127.0.0.1
    Connection Limit:    1
    Expiration:          Wed, 30 Sep 2020 23:18:14 MST
    Port:                61991
    Protocol:            tcp
    Session ID:          s_h7vBIhH5SZ
```

For more information regarding different ways to connect to a target behind Boundary see [Connect to Target](/boundary/docs/getting-started/connect-to-target) under Getting Started and [Advanced Session Establishment](#advanced-session-establishment) below.

## View Sessions

<Tabs>
<Tab heading="CLI">

View all sessions which Boundary has for the project `p_1234567890` by listing them.

```bash
$ boundary sessions list -scope-id p_1234567890

Session information:
    ID:                 s_h7vBIhH5SZ
        Status:           active
        Created Time:     2020-09-30T15:18:14-07:00
        Expiration Time:  2020-09-30T23:18:14-07:00
        Updated Time:     2020-09-30T15:18:35-07:00
        User ID:          u_1234567890
        Target ID:        ttcp_1234567890
```

We can get a more detailed view of a specific session by reading it.

```bash
$ boundary sessions read -id s_h7vBIhH5SZ

Session information:
    Auth Token ID:       at_51XQGx0bzk
    Created Time:        Wed, 30 Sep 2020 15:18:14 MST
    Endpoint:            tcp://localhost:22
    Expiration Time:     2020-09-30T23:18:14-07:00
    Host ID:             hst_1234567890
    Host Set ID:         hsst_1234567890
    ID:                  s_h7vBIhH5SZ
    Status:              active
    Target ID:           ttcp_1234567890
    Type:                tcp
    Updated Time:        2020-09-30T15:18:35-07:00
    User ID:             u_1234567890
    Version:             2

    Scope:
        ID:                p_1234567890
        Name:              Generated project scope
        Parent Scope ID:   o_1234567890
        Type:              project

    States:
        Start Time:        Wed, 30 Sep 2020 15:18:35 MST
        Status:            active

        End Time:          Wed, 30 Sep 2020 15:18:35 MST
        Start Time:        Wed, 30 Sep 2020 15:18:14 MST
        Status:            pending
```

</Tab>
<Tab heading="Admin Console">

1.  Navigate to a project, then to sessions.
1.  View the session information provided there.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
    <source
        type="video/mp4"
        src="https://www.datocms-assets.com/2885/1602532864-boundary-clickthrough-manage-sessions-view-sessions.mp4"
    />
</video>
</Tab>
</Tabs>

## Cancel a Session

<Tabs>
<Tab heading="CLI">
To send a request to Boundary to cancel a session:

```bash
$ boundary sessions cancel -id s_h7vBIhH5SZ

Session information:
    Auth Token ID:       at_51XQGx0bzk
    Created Time:        Wed, 30 Sep 2020 15:18:14 MST
    Endpoint:            tcp://localhost:22
    Expiration Time:     2020-09-30T23:18:14-07:00
    Host ID:             hst_1234567890
    Host Set ID:         hsst_1234567890
    ID:                  s_h7vBIhH5SZ
    Status:              canceling
    Target ID:           ttcp_1234567890
    Type:                tcp
    Updated Time:        2020-09-30T15:19:17-07:00
    User ID:             u_1234567890
    Version:             3

    Scope:
        ID:                p_1234567890
        Name:              Generated project scope
        Parent Scope ID:   o_1234567890
        Type:              project

    States:
        Start Time:        Wed, 30 Sep 2020 15:19:17 MST
        Status:            canceling

        End Time:          Wed, 30 Sep 2020 15:19:17 MST
        Start Time:        Wed, 30 Sep 2020 15:18:35 MST
        Status:            active

        End Time:          Wed, 30 Sep 2020 15:18:35 MST
        Start Time:        Wed, 30 Sep 2020 15:18:14 MST
        Status:            pending
```

Boundary then cancels the session and move it into a "Terminated" state.

</Tab>
<Tab heading="Admin Console">

1. Navigate to a project, then to sessions.
1. Choose a session and its **Cancel** button.
1. View the session status update from _canceling_ to _terminated_.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
    <source
        type="video/mp4"
        src="https://www.datocms-assets.com/2885/1602261010-boundary-clickthrough-manage-sessions-cancel-session.mp4"
    />
</video>
</Tab>
</Tabs>

## Advanced Session Establishment

Above, we discussed connecting to a target using the `boundary connect` command. In addition to this we can create a session to a target and connect to that session in separate steps. This is accomplished using the `boundary targets authorize-session` command, which generates an authorization token that a user can use to start a session via `boundary connect -authz-token` at their own convenience.

```bash
$ boundary targets authorize-session -id ttcp_1234567890

Target information:
    Authorization Token:   $LONG_STRING_OF_TEXT
    Created Time:          2020-09-30T15:18:14-07:00
    Host ID:               hst_1234567890
    Scope ID:              p_1234567890
    Session ID:            s_h7vBIhH5SZ
    Target ID:             ttcp_1234567890
    Type:                  tcp
    User ID:               u_1234567890
```

Note: You can also provide a `-host-id` flag in the request above which ensures connecting using the provided Authorization Token will connect you to this specific host.

```bash
$ boundary connect -authz-token $LONG_STRING_OF_TEXT

Proxy listening information:
    Address:             127.0.0.1
    Connection Limit:    1
    Expiration:          Wed, 30 Sep 2020 23:18:14 MST
    Port:                61991
    Protocol:            tcp
    Session ID:          s_h7vBIhH5SZ
```

With the above address and port information we can now connect to our local proxy and have our tcp traffic sent through the Boundary system.

```bash
$ ssh 127.0.0.1 -p 61991
...
```