Manage sessions

8min
|
Boundary

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.

This tutorial demonstrates the basics of how to start a session, view the session details and cancel a session in Boundary.

Prerequisites

This tutorial assumes that you successfully completed the Manage Scopes and Manage Targets tutorials.

Retrieve resource IDs

To connect to a target, you need the target ID and host ID to use the -host-id flag. If you are not sure about those IDs, follow the steps in this section; otherwise, skip to the Start a session section.

Log back into the CLI as the admin user. Enter password at the Please enter the password (it will be hidden): prompt.

$ boundary authenticate password \  -auth-method-id=ampw_1234567890 \  -login-name=admin

List the existing targets under the QA_Tests project.

$ boundary targets list -scope-id=$PROJECT_IDTarget information:  ID:                    ttcp_34yV5O9cwt    Version:             2    Type:                tcp    Name:                tests    Description:         Test target    Authorized Actions:      no-op      read      update      delete      add-host-sources      set-host-sources      remove-host-sources      add-credential-libraries      set-credential-libraries      remove-credential-libraries      add-credential-sources      set-credential-sources      remove-credential-sources      authorize-session

Now, you have the target ID (e.g. ttcp_34yV5O9cwt).

If you haven't already, copy the ID and save it as an environment variable, TARGET_ID.

Example:

$ export TARGET_ID=ttcp_34yV5O9cwt

List the host IDs that belong to the host catalog.

$ boundary hosts list -host-catalog-id=$HOST_CATALOG_IDHost information:  ID:                    hst_FrdNPd9Zm9    Version:             1    Type:                static    Name:                localhost    Description:         Localhost for testing    Authorized Actions:      no-op      read      update      delete  ID:                    hst_U1qYKzKfXO    Version:             1    Type:                static    Name:                postgres    Description:         Postgres host    Authorized Actions:      no-op      read      update      delete

Copy the localhost host ID. In the example output, the ID is hst_FrdNPd9Zm9.

Start a session

Open a session to the postgres target using boundary connect. When prompted, enter the password secret to connect.

$ boundary connect postgres -target-id $TARGET_ID -username postgresPassword for user postgres:psql (13.2)Type "help" for help.postgres=#

Note

If you followed the Admin Console workflow and did not export the TARGET_ID environment variable, supply it directly instead. such as ttcp_34yV5O9cwt.

Open a session to the postgres target using the Boundary Desktop App.

Open the Desktop App and enter http://127.0.0.1:9200 for the Cluster URL.

Desktop Cluster URL

Select the IT_Support scope in the upper-left corner of the app.

Navigate to the Targets view.

Boundary Desktop Targets

Click Connect beside the postgres target.

Connect to target

Copy the Proxy URL, such as 127.0.0.1:59801.

Next, select the Terminal tab, or open a new terminal session. Use the psql client to establish a session with the postgres container via the local proxy created by Boundary. Enter the password secret when prompted for the sampledb database password.

$ psql -h 127.0.0.1 -p 59801 -d sampledb -U postgresPassword for user postgres:psql (14.2, server 15.1 (Debian 15.1-1.pgdg110+1))WARNING: psql major version 14, server major version 15.         Some psql features might not work.Type "help" for help.sampledb=#

Connect to postgres

For more information regarding different ways to connect to a target behind Boundary see Connect to Target and the Advanced Session Establishment section.

View sessions

Note

After connecting to the postgres container, the exported environment variables may no longer be available in your shell session. Leave this session open, and open a new terminal window to proceed.

Log back into the CLI as the admin user. Enter password at the Please enter the password (it will be hidden): prompt.

$ boundary authenticate password \  -auth-method-id=ampw_1234567890 \  -login-name=admin

List the available scopes.

$ boundary scopes list -recursiveScope information:  ID:                    o_1234567890    Scope ID:            global    Version:             1    Name:                Generated org scope    Description:         Provides an initial org scope in Boundary    Authorized Actions:      no-op      read      update      delete  ID:                    o_u54jrD6ydN    Scope ID:            global    Version:             1    Name:                IT_Support    Description:         IT Support Team    Authorized Actions:      no-op      read      update      delete  ID:                    p_1234567890    Scope ID:            o_1234567890    Version:             1    Name:                Generated project scope    Description:         Provides an initial project scope in Boundary    Authorized Actions:      no-op      read      update      delete  ID:                    p_oMgeFL2hP6    Scope ID:            o_u54jrD6ydN    Version:             1    Name:                QA_Tests    Description:         Manage QA machines    Authorized Actions:      no-op      read      update      delete

Copy the QA_Tests project scope ID, such as p_oMgeFL2hP6.

View all sessions which Boundary has under the QA_Tests project by listing them.

$ boundary sessions list -scope-id=p_oMgeFL2hP6Session information:  ID:                    s_gEbbaTbBw2    Status:              active    Created Time:        Tue, 24 Jan 2023 17:09:53 MST    Expiration Time:     Wed, 25 Jan 2023 01:09:53 MST    Updated Time:        Tue, 24 Jan 2023 17:09:53 MST    User ID:             u_1234567890    Target ID:           ttcp_wtXnow8Krb    Authorized Actions:      no-op      read      read:self      cancel      cancel:self

We can get a more detailed view of a specific session by reading it.

$ boundary sessions read -id=s_nUho4KvZcLSession information:  Auth Token ID:       at_CMcMUgC23p  Created Time:        Tue, 24 Jan 2023 17:09:53 MST  Endpoint:            tcp://127.0.0.1:16001  Expiration Time:     Wed, 25 Jan 2023 01:09:53 MST  Host ID:             hst_DHei2VpkBH  Host Set ID:         hsst_LzkHrusOQt  ID:                  s_gEbbaTbBw2  Status:              active  Target ID:           ttcp_wtXnow8Krb  Type:                tcp  Updated Time:        Tue, 24 Jan 2023 17:09:53 MST  User ID:             u_1234567890  Version:             2  Scope:    ID:                p_VF6GGqKxMz    Name:              QA_Tests    Parent Scope ID:   o_aKfCM4fHnU    Type:              project  Authorized Actions:    no-op    read    read:self    cancel    cancel:self  States:    Start Time:        Tue, 24 Jan 2023 17:09:53 MST    Status:            active    End Time:          Tue, 24 Jan 2023 17:09:53 MST    Start Time:        Tue, 24 Jan 2023 17:09:53 MST    Status:            pending  Connections:    Bytes Down:        587    Bytes Up:          256    Client Address:    127.0.0.1:60434    Endpoint Address:  127.0.0.1:16001    Bytes Down:        25    Bytes Up:          92    Client Address:    127.0.0.1:60429    Closed Reason:     unknown    Endpoint Address:  127.0.0.1:16001

Cancel a session

If unexpected activity is detected, you can force-cancel the session.

Cancel the session using the session ID copied in the previous step.

$ boundary sessions cancel -id=s_nUho4KvZcLSession information:  Auth Token ID:        at_CMcMUgC23p  Created Time:         Tue, 24 Jan 2023 17:09:53 MST  Endpoint:             tcp://127.0.0.1:16001  Expiration Time:      Wed, 25 Jan 2023 01:09:53 MST  Host ID:              hst_DHei2VpkBH  Host Set ID:          hsst_LzkHrusOQt  ID:                   s_gEbbaTbBw2  Status:               terminated  Target ID:            ttcp_wtXnow8Krb  Termination Reason:   canceled  Type:                 tcp  Updated Time:         Tue, 24 Jan 2023 17:20:58 MST  User ID:              u_1234567890  Version:              5  Scope:    ID:                 p_VF6GGqKxMz    Name:               QA_Tests    Parent Scope ID:    o_aKfCM4fHnU    Type:               project  Authorized Actions:    no-op    read    read:self    cancel    cancel:self  States:    Start Time:         Tue, 24 Jan 2023 17:12:43 MST    Status:             canceling    End Time:           Tue, 24 Jan 2023 17:12:43 MST    Start Time:         Tue, 24 Jan 2023 17:09:53 MST    Status:             active    End Time:           Tue, 24 Jan 2023 17:09:53 MST    Start Time:         Tue, 24 Jan 2023 17:09:53 MST    Status:             pending

The status is now canceling. When it completes, the session status will change to terminated.

Wait a moment, and then read the session details.

$ boundary sessions read -id=s_nUho4KvZcLSession information:  Auth Token ID:        at_CMcMUgC23p  Created Time:         Tue, 24 Jan 2023 17:09:53 MST  Endpoint:             tcp://127.0.0.1:16001  Expiration Time:      Wed, 25 Jan 2023 01:09:53 MST  Host ID:              hst_DHei2VpkBH  Host Set ID:          hsst_LzkHrusOQt  ID:                   s_gEbbaTbBw2  Status:               terminated  Target ID:            ttcp_wtXnow8Krb  Termination Reason:   canceled  Type:                 tcp  Updated Time:         Tue, 24 Jan 2023 17:25:59 MST  User ID:              u_1234567890  Version:              5  Scope:    ID:                 p_VF6GGqKxMz    Name:               QA_Tests    Parent Scope ID:    o_aKfCM4fHnU    Type:               project  Authorized Actions:    no-op    read    read:self    cancel    cancel:self  States:    Start Time:         Tue, 24 Jan 2023 17:12:43 MST    Status:             terminated    End Time:           Tue, 24 Jan 2023 17:12:43 MST    Start Time:         Tue, 24 Jan 2023 17:12:43 MST    Status:             canceling    End Time:           Tue, 24 Jan 2023 17:12:43 MST    Start Time:         Tue, 24 Jan 2023 17:09:53 MST    Status:             active    End Time:           Tue, 24 Jan 2023 17:09:53 MST    Start Time:         Tue, 24 Jan 2023 17:09:53 MST    Status:             pending  Connections:    Bytes Down:         587    Bytes Up:           256    Client Address:     127.0.0.1:60434    Closed Reason:      unknown    Endpoint Address:   127.0.0.1:16001    Bytes Down:         25    Bytes Up:           92    Client Address:     127.0.0.1:60429    Closed Reason:      unknown    Endpoint Address:   127.0.0.1:16001

Click on the Cancel button to cancel a particular session.

Cancelled sessions

The session status becomes canceling and then terminated.

If you attempt to run a command in the existing psql shell you will receive a connection error because Boundary has terminated the session:

$ postgres=# \dserver closed the connection unexpectedly    This probably means the server terminated abnormally    before or while processing the request.The connection to the server was lost. Attempting reset: Unable to authorize connectionFailed.!?>

Advanced session establishment

In addition to the boundary connect command, you 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=<target_id> -host-id=<host_id>

For this example, gather the target ID and host ID as demonstrated in the previous tutorials:

List all targets.

$ boundary targets list -recursive

Copy the postgres target ID.

List all host catalogs.

$ boundary host-catalogs list -recursive

Copy the DevOps host catalog ID, and then list all hosts within the host catalog.

$ boundary hosts list -host-catalog-id=<HOST_CATALOG_ID>

Then copy the localhost host ID, such as hst_FrdNPd9Zm9.

With these IDs gathered, generate an authorize token for the localhost host.

Example:

$ boundary targets authorize-session -id=ttcp_wtXnow8Krb -host-id=hst_DHei2VpkBHTarget information:  Authorization Token:  3vYggdcgyASTqU5dvh8vXLkohH9e3PzPyLLoZUXaVFFu4kDFSjoMDx5SzH5X7yjNdF4K6SkVxhAKjhK3fFufFUs7GUxfMVsPC6YdA6gp57FqzGSogRVjGpi4LtsqgedE4GpHzfkV3bYkz8YxqLbpBRV4ZtPSmvtvTxJZtLXZLSzpeWvJdB2r5Gq7uhqEe81aMUZKEZcwd5TpS79VwKnD3USyw9mdo7SNbe32G6Vru3BMgQRk5KYX7QUNJUCUVAzmMp9m2G7jDpzZUW7dyvq58rpYwGGVZYRjuwF87KN3i34o6oJ7kUSYr1vvd58JjVzsWncEpAGMxyt9RcHd4vKgDyYbV5gdHHfKdMyDBB7NFAXXzRjCXeF8k7yFZ2rT973dBBpN4GyGcF1Xq9YfMRAE2QTXC9noJ2zdadruQoWZRsRpWm3mdLbiXWXE4AtGkTG6eyQ2bgyBK8BmZk3k4AJrkzpMAcSd8NfCcAFaPnvpGZgAMMBz2sZJ6CBahxeW1A55ccqBVgT95ZL77wBA57Pmia4Hfz38KpbeTtwDBK6CuW16C1aRGnwzajwsFeYSL4vJgLfDhJvjkfKK5mLwYJtcp2gVqxbQMZvDSqGXM1TQHC8g74JfpxLE6oQEBZ7yjGWT32zd4kaQufceN7biiZAJSiVqxPGpRGfgMcW4ZLTq8DALWtviA1p4aFJETzedDoJ4c16wnL2GoHgHtsT7xUjZvKq7v659Psg55iKgNQmrt2ubHoU3GcLK54UQ7ho27wMZdPgSu6Xv2nUjcG7f6CaaDkYgCKTq1b  Created Time:          Tue, 24 Jan 2023 17:26:33 MST  Endpoint:              tcp://127.0.0.1:16001  Host ID:               hst_DHei2VpkBH  Scope ID:              p_VF6GGqKxMz  Session ID:            s_mraN5QJr7t  Target ID:             ttcp_wtXnow8Krb  Type:                  tcp  User ID:               u_1234567890

Copy the generated Authorization Token value.

Note

In the absence of -host-id flag, Boundary will pick a host from the host set. If there is more than one host in the host set attached to the target, one is selected automatically.

$ boundary connect -authz-token=<authorization_token>

Example:

$ boundary connect -authz-token="3vYggdcgyASTqU5dvh8vXLkohH9e3PzPyLLoZUXaVFFu4kDFSjoMDx5SzH5X7yjNdF4K6SkVxhAKjhK3fFufFUs7GUxfMVsPC6YdA6gp57FqzGSogRVjGpi4LtsqgedE4GpHzfkV3bYkz8YxqLbpBRV4ZtPSmvtvTxJZtLXZLSzpeWvJdB2r5Gq7uhqEe81aMUZKEZcwd5TpS79VwKnD3USyw9mdo7SNbe32G6Vru3BMgQRk5KYX7QUNJUCUVAzmMp9m2G7jDpzZUW7dyvq58rpYwGGVZYRjuwF87KN3i34o6oJ7kUSYr1vvd58JjVzsWncEpAGMxyt9RcHd4vKgDyYbV5gdHHfKdMyDBB7NFAXXzRjCXeF8k7yFZ2rT973dBBpN4GyGcF1Xq9YfMRAE2QTXC9noJ2zdadruQoWZRsRpWm3mdLbiXWXE4AtGkTG6eyQ2bgyBK8BmZk3k4AJrkzpMAcSd8NfCcAFaPnvpGZgAMMBz2sZJ6CBahxeW1A55ccqBVgT95ZL77wBA57Pmia4Hfz38KpbeTtwDBK6CuW16C1aRGnwzajwsFeYSL4vJgLfDhJvjkfKK5mLwYJtcp2gVqxbQMZvDSqGXM1TQHC8g74JfpxLE6oQEBZ7yjGWT32zd4kaQufceN7biiZAJSiVqxPGpRGfgMcW4ZLTq8DALWtviA1p4aFJETzedDoJ4c16wnL2GoHgHtsT7xUjZvKq7v659Psg55iKgNQmrt2ubHoU3GcLK54UQ7ho27wMZdPgSu6Xv2nUjcG7f6CaaDkYgCKTq1b"Proxy listening information:  Address:             127.0.0.1  Connection Limit:    -1  Expiration:          Wed, 25 Jan 2023 01:26:33 MST  Port:                61617  Protocol:            tcp  Session ID:          s_mraN5QJr7t

With the above address and port information, you can connect to the local proxy and have your tcp traffic sent through the Boundary system.

Copy the Port (such as 61617) and note the Address (127.0.0.1).

Open a new terminal window.

Attempt to establish an ssh session to the postgres container again.

When prompted, enter the sampledb password secret.

$ psql -h 127.0.0.1 -p 61617 -d sampledb -U postgresPassword for user postgres:psql (14.2, server 15.1 (Debian 15.1-1.pgdg110+1))WARNING: psql major version 14, server major version 15.         Some psql features might not work.Type "help" for help.sampledb=#

Practice cancelling the session, as demonstrated before.

Summary

The Manage Scopes tutorial demonstrated the steps to create a new org (IT_Support) and a project (QA_Tests) under the org.

The Manage Targets tutorial demonstrated the creation of a host catalog, a host set, and hosts. Then, associated the host set to a target.

You also enabled a new authorization method (password) for the IT_Support org and created a new user in the Manage Users and Groups tutorial. The Manage Roles and Permissions tutorial showed you how to create a role and assign a grant which specifies a set of permissions.

Finally, this tutorial demonstrated session management based on the target you defined for the QA_Tests project.

To continue learning about Boundary, check out the Self-Hosted Administration Workflows.

Manage roles and permissions

Manage workers