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

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

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

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

Cancel a Session

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 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

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

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...