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.

  1. $ boundary connect ssh -target-id ttcp_1234567890 --
  2. Proxy listening information:
  3. Address: 127.0.0.1
  4. Connection Limit: 1
  5. Expiration: Wed, 30 Sep 2020 23:18:14 MST
  6. Port: 61991
  7. Protocol: tcp
  8. Session ID: s_h7vBIhH5SZ
  1. $ boundary connect ssh -target-id ttcp_1234567890 --
  2. 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.

  1. $ boundary sessions list -scope-id p_1234567890
  2. Session information:
  3. ID: s_h7vBIhH5SZ
  4. Status: active
  5. Created Time: 2020-09-30T15:18:14-07:00
  6. Expiration Time: 2020-09-30T23:18:14-07:00
  7. Updated Time: 2020-09-30T15:18:35-07:00
  8. User ID: u_1234567890
  9. Target ID: ttcp_1234567890
  1. $ boundary sessions list -scope-id p_1234567890
  2. 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.

  1. $ boundary sessions read -id s_h7vBIhH5SZ
  2. Session information:
  3. Auth Token ID: at_51XQGx0bzk
  4. Created Time: Wed, 30 Sep 2020 15:18:14 MST
  5. Endpoint: tcp://localhost:22
  6. Expiration Time: 2020-09-30T23:18:14-07:00
  7. Host ID: hst_1234567890
  8. Host Set ID: hsst_1234567890
  9. ID: s_h7vBIhH5SZ
  10. Status: active
  11. Target ID: ttcp_1234567890
  12. Type: tcp
  13. Updated Time: 2020-09-30T15:18:35-07:00
  14. User ID: u_1234567890
  15. Version: 2
  16. Scope:
  17. ID: p_1234567890
  18. Name: Generated project scope
  19. Parent Scope ID: o_1234567890
  20. Type: project
  21. States:
  22. Start Time: Wed, 30 Sep 2020 15:18:35 MST
  23. Status: active
  24. End Time: Wed, 30 Sep 2020 15:18:35 MST
  25. Start Time: Wed, 30 Sep 2020 15:18:14 MST
  26. Status: pending
  1. $ boundary sessions read -id s_h7vBIhH5SZ
  2. 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
  3. Scope: ID: p_1234567890 Name: Generated project scope Parent Scope ID: o_1234567890 Type: project
  4. States: Start Time: Wed, 30 Sep 2020 15:18:35 MST Status: active
  5. 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:

  1. $ boundary sessions cancel -id s_h7vBIhH5SZ
  2. Session information:
  3. Auth Token ID: at_51XQGx0bzk
  4. Created Time: Wed, 30 Sep 2020 15:18:14 MST
  5. Endpoint: tcp://localhost:22
  6. Expiration Time: 2020-09-30T23:18:14-07:00
  7. Host ID: hst_1234567890
  8. Host Set ID: hsst_1234567890
  9. ID: s_h7vBIhH5SZ
  10. Status: canceling
  11. Target ID: ttcp_1234567890
  12. Type: tcp
  13. Updated Time: 2020-09-30T15:19:17-07:00
  14. User ID: u_1234567890
  15. Version: 3
  16. Scope:
  17. ID: p_1234567890
  18. Name: Generated project scope
  19. Parent Scope ID: o_1234567890
  20. Type: project
  21. States:
  22. Start Time: Wed, 30 Sep 2020 15:19:17 MST
  23. Status: canceling
  24. End Time: Wed, 30 Sep 2020 15:19:17 MST
  25. Start Time: Wed, 30 Sep 2020 15:18:35 MST
  26. Status: active
  27. End Time: Wed, 30 Sep 2020 15:18:35 MST
  28. Start Time: Wed, 30 Sep 2020 15:18:14 MST
  29. Status: pending
  1. $ boundary sessions cancel -id s_h7vBIhH5SZ
  2. 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
  3. Scope: ID: p_1234567890 Name: Generated project scope Parent Scope ID: o_1234567890 Type: project
  4. States: Start Time: Wed, 30 Sep 2020 15:19:17 MST Status: canceling
  5. End Time: Wed, 30 Sep 2020 15:19:17 MST Start Time: Wed, 30 Sep 2020 15:18:35 MST Status: active
  6. 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.

  1. $ boundary targets authorize-session -id ttcp_1234567890
  2. Target information:
  3. Authorization Token: $LONG_STRING_OF_TEXT
  4. Created Time: 2020-09-30T15:18:14-07:00
  5. Host ID: hst_1234567890
  6. Scope ID: p_1234567890
  7. Session ID: s_h7vBIhH5SZ
  8. Target ID: ttcp_1234567890
  9. Type: tcp
  10. User ID: u_1234567890
  1. $ boundary targets authorize-session -id ttcp_1234567890
  2. 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.

  1. $ boundary connect -authz-token $LONG_STRING_OF_TEXT
  2. Proxy listening information:
  3. Address: 127.0.0.1
  4. Connection Limit: 1
  5. Expiration: Wed, 30 Sep 2020 23:18:14 MST
  6. Port: 61991
  7. Protocol: tcp
  8. Session ID: s_h7vBIhH5SZ
  1. $ boundary connect -authz-token $LONG_STRING_OF_TEXT
  2. 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.

  1. $ ssh 127.0.0.1 -p 61991
  2. ...
  1. $ ssh 127.0.0.1 -p 61991...