Manage Sessions
Sessions are Boundary resources created when connecting to a Target. 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 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, 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.
$ 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
$ 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 under Getting Started and Advanced Session Establishment below.
View Sessions
CLIAdmin Console
View all sessions which Boundary has for the project p_1234567890
by listing them.
$ 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
$ 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.
$ 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
$ 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
Cancel a Session
CLIAdmin Console
To send a request to Boundary to cancel a session:
$ 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 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.
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.
$ 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
$ 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.
$ 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
$ 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.
$ ssh 127.0.0.1 -p 61991
...
$ ssh 127.0.0.1 -p 61991...