From e0285a00ea947fed0d4163e1e7c64dfa988e67ed Mon Sep 17 00:00:00 2001 From: Todd Knight Date: Thu, 1 Oct 2020 09:39:34 -0700 Subject: [PATCH] Document CLI commands for session management (#514) * Documentation for how to manage sessions using the CLI. UI is still a TODO. * Removing TODO under the UI tab. --- .../docs/common-workflows/manage-sessions.mdx | 177 ++++++++++++++++++ 1 file changed, 177 insertions(+) diff --git a/website/content/docs/common-workflows/manage-sessions.mdx b/website/content/docs/common-workflows/manage-sessions.mdx index b14d9dad6..a6ff34938 100644 --- a/website/content/docs/common-workflows/manage-sessions.mdx +++ b/website/content/docs/common-workflows/manage-sessions.mdx @@ -6,3 +6,180 @@ description: How to manage Boundary sessions --- # Manage Sessions + +[Sessions](/docs/concepts/domain-model/sessions) are Boundary resources which enables connecting to a [target](/docs/concepts/domain-model/target). A target allows Boundary users to define an endpoint with a default-port and a protocol 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 to connect to at random. + +In this section, we'll show you the basics of how to start a session in Boundary on the CLI and the admin console. + +We assume you're running Boundary in dev mode and have a default target of `ttcp_1234567890`. We also assume you've logged in on the command line and the admin console. See the output of `boundary dev` for these login values. + +## Authorize with a target + +For this example, we're going to authorize that you are able to connect to a target which results in an Authorization Token being returned which can be used to connect to the session through the proxy. + + + + + ```bash + $ boundary targets authorize -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. + +## Connect to the session + +Once we have received an Authorization Token a Boundary session has been created and is waiting to proxy connection to the target. We'll now connect our local proxy to the Boundary deployment. + + + + + ```bash + $ boundary proxy -authz $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 +... +``` + +For SSH connections we'll likely receive a notice that the authenticity of the host can't be established. + +## Viewing Sessions + +Beyond establishing sessions we can also view and cancel sessions. Here we'll view all sessions that have recently happened in the project scope that are default target is in. + + + + + ```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 this 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 + + ``` + + + + +## Cancelling Sessions + +To shut down a session the person initiating the connection can disconnect all connections or a request can be sent to Boundary to cancel a specific 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 will then cancel the session and move it into a "Terminated" state.