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_ID

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

Host 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 postgres
Password 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 postgres
Password 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 -recursive

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

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

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

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

Session 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=# \d
server 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 connection
Failed.
!?>

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_DHei2VpkBH

Target 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 postgres
Password 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