Bryce Kalow
bd8cc5464e
* migrates nav data format and updates docs pages * removes sidebar_title from content files * updates api docs to work with new format
202 lines
7.0 KiB
Plaintext
202 lines
7.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Manage Sessions
|
|
description: How to manage Boundary sessions
|
|
---
|
|
|
|
# Manage Sessions
|
|
|
|
[Sessions](/docs/concepts/domain-model/sessions) are Boundary resources created when connecting to a [Target](/docs/concepts/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](/docs/concepts/domain-model/hosts) from the target's [Host Sets](/docs/concepts/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](/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
|
|
...
|
|
```
|