News HashiCorp to join IBM to accelerate multi-cloud automation. Read the blog →
Boundary
HCP administration

Manage sessions with HCP Boundary

  • 8min
  • |
  • HCP
  • 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.

Note

All resource IDs in this tutorial are illustrations only. IDs are uniquely generated for every resource upon creation. Be sure to use the resource IDs that are generated for your environment.

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=$BOUNDARY_AUTH_METHOD_ID \  -login-name=admin

  1. List the existing targets under the QA_Tests project.

    $ boundary targets list -scope-id=$PROJECT_ID Target information:  ID:                    ttcp_34yV5O9cwt    Version:             4    Type:                tcp    Name:                ubuntu-target    Description:         Ubuntu target    Authorized Actions:      no-op      read      update      delete      add-host-sources      set-host-sources      remove-host-sources      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

  2. 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:                ubuntu    Description:         Ubuntu host    Authorized Actions:      no-op      read      update      delete

  1. Copy the generated host ID and create an environment variable called HOST_ID using copied value. In the example output, the ID is hst_FrdNPd9Zm9.

    $ export HOST_ID=<ubuntu_host_id>

Now, you have the target ID and host ID.

Start a session

You are now ready to connect to the target and establish a session.

  1. Retrieve the public IP address of your Ubuntu instance and export the address as an environment variable. Replace public-ip with the actual IP address.

    $ export UBUNTU_IP=public-ip

  2. Export an environment variable for your Ubuntu host's username and path to the private key. Replace the username and path to the key file with valid values for your host.

    $ export UBUNTU_USER=actualusername UBUNTU_KEY=private_key.pem

  3. Connect to the ubuntu-target using Boundary.

    $ boundary connect ssh -target-id=$TARGET_ID -host-id=$HOST_ID -- -l $UBUNTU_USER -i $UBUNTU_KEYThe authenticity of host 'ec2-198-52-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.Are you sure you want to continue connecting (yes/no)? yes Welcome to Ubuntu 22.04.2 LTS (GNU/Linux 5.19.0-1025-aws x86_64)  * Documentation:  https://help.ubuntu.com * Management:     https://landscape.canonical.com * Support:        https://ubuntu.com/advantage ubuntu@ip-172-32-88-177:~

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

Leave this session open, and open a new terminal window to proceed. Note that the exported environment variables will no longer be available in the new shell session.

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=$BOUNDARY_AUTH_METHOD_ID \  -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_7JwF1yMY2g    Status:              active    Created Time:        Thu, 24 Aug 2023 16:35:40 MDT    Expiration Time:     Fri, 25 Aug 2023 00:35:40 MDT    Updated Time:        Thu, 24 Aug 2023 16:35:41 MDT    User ID:             u_r1jtIlLsjK    Target ID:           ttcp_TV3E2bW91i    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_7JwF1yMY2g Session information:  Auth Token ID:       at_wdKAieLzv8  Created Time:        Thu, 24 Aug 2023 16:35:40 MDT  Endpoint:            tcp://3.88.69.227:22  Expiration Time:     Fri, 25 Aug 2023 00:35:40 MDT  Host ID:             hst_7Jeh2Z1mKk  Host Set ID:         hsst_qzAKjQKXgq  ID:                  s_7JwF1yMY2g  Status:              active  Target ID:           ttcp_TV3E2bW91i  Type:                tcp  Updated Time:        Thu, 24 Aug 2023 16:35:41 MDT  User ID:             u_r1jtIlLsjK  Version:             2   Scope:    ID:                p_ZWc13Om0sf    Name:              QA_Tests    Parent Scope ID:   o_GHxE1QbtE5    Type:              project   Authorized Actions:    no-op    read    read:self    cancel    cancel:self   States:    Start Time:        Thu, 24 Aug 2023 16:35:41 MDT    Status:            active     End Time:          Thu, 24 Aug 2023 16:35:41 MDT    Start Time:        Thu, 24 Aug 2023 16:35:40 MDT    Status:            pending    Connections:    Bytes Down:        7129    Bytes Up:          4461    Client Address:    172.17.0.1:37856    Endpoint Address:  3.88.69.227:22

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_7JwF1yMY2g Session information:  Auth Token ID:       at_wdKAieLzv8  Created Time:        Thu, 24 Aug 2023 16:35:40 MDT  Endpoint:            tcp://3.88.69.227:22  Expiration Time:     Fri, 25 Aug 2023 00:35:40 MDT  Host ID:             hst_7Jeh2Z1mKk  Host Set ID:         hsst_qzAKjQKXgq  ID:                  s_7JwF1yMY2g  Status:              canceling  Target ID:           ttcp_TV3E2bW91i  Type:                tcp  Updated Time:        Thu, 24 Aug 2023 16:38:05 MDT  User ID:             u_r1jtIlLsjK  Version:             3   Scope:    ID:                p_ZWc13Om0sf    Name:              QA_Tests    Parent Scope ID:   o_GHxE1QbtE5    Type:              project   Authorized Actions:    no-op    read    read:self    cancel    cancel:self   States:    Start Time:        Thu, 24 Aug 2023 16:38:05 MDT    Status:            canceling     End Time:          Thu, 24 Aug 2023 16:38:05 MDT    Start Time:        Thu, 24 Aug 2023 16:35:41 MDT    Status:            active     End Time:          Thu, 24 Aug 2023 16:35:41 MDT    Start Time:        Thu, 24 Aug 2023 16:35:40 MDT    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_7JwF1yMY2g Session information:  Auth Token ID:        at_wdKAieLzv8  Created Time:         Thu, 24 Aug 2023 16:35:40 MDT  Endpoint:             tcp://3.88.69.227:22  Expiration Time:      Fri, 25 Aug 2023 00:35:40 MDT  Host ID:              hst_7Jeh2Z1mKk  Host Set ID:          hsst_qzAKjQKXgq  ID:                   s_7JwF1yMY2g  Status:               terminated  Target ID:            ttcp_TV3E2bW91i  Termination Reason:   canceled  Type:                 tcp  Updated Time:         Thu, 24 Aug 2023 16:38:06 MDT  User ID:              u_r1jtIlLsjK  Version:              5   Scope:    ID:                 p_ZWc13Om0sf    Name:               QA_Tests    Parent Scope ID:    o_GHxE1QbtE5    Type:               project   Authorized Actions:    no-op    read    read:self    cancel    cancel:self   States:    Start Time:         Thu, 24 Aug 2023 16:38:06 MDT    Status:             terminated     End Time:           Thu, 24 Aug 2023 16:38:06 MDT    Start Time:         Thu, 24 Aug 2023 16:38:05    MDT    Status:             canceling   Connections:    Bytes Down:         12585    Bytes Up:           8609    Client Address:     172.17.0.1:37856    Closed Reason:      unknown    Endpoint Address:   3.88.69.227:22

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 tests target ID.

List all host catalogs.

$ boundary host-catalogs list -recursive

You created the DevOps host catalog during the Manage Targets with HCP Boundary tutorial.

List and review the available hosts created previously.

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

Generate an authorization token for the ubuntu host.

Example:

$ boundary targets authorize-session -id=$TARGET_ID -host-id=$HOST_ID Target information:  Authorization Token:  KrPM2b5ikACAhdm7RBMHC2rsrunbSGwsK8BDVLYkraQ9D5KZgS8gTfNGjbfzxnpdRfQt5V8ErX1hrvNZn4DLLTHXXjXhLMuFvwKjUi8xEfgNkvqrYwrXbYB3gR49cu7hvgfKCNTbkrT4per5XYdbKaJhRmUZ7vkpgzrGpC8cCgZK5cfNRAwZ4yaP6HrgpoVsWZm96r43Qpzztq3qBDQsssXueqqmckSpEEsKce5ev6CPXhAT4PwTxZ8ALJfHArqxE4p5WrDCs93RTzGn6zzbGPuCQ5TuSwYKqSqk7y8ZR85vWrSJuqDdyf35fyNdk5miY9AnSaghh1sppoia1NijDXuTXb8RMbpJcy5rqxQgvbnxDRSN9b5Ca2N12rzAChcvSCB2koTqtF8kY24vhvjoVf8hbWHc3TGvevUEASEGEuGXzxh2UF7P9WrMonage3xiEwpnJhXvdu8vCsyXG2jds3ygFwFqhGdeac8gU6CEN5Ud6YM78UhqAXeXmAdkcq7J9ySneHowHrqQH71rhPXH7E9r7ah8Da3yvhvYG6Lz36it321bEFknkTPHPoegUCc8QHjtfJCA6M3m7NEc7JBksZnC5LskVapbY5QgHdGcfXu5Gt8mFfU7xUojzZW42v8DmLzxXY6ZTjWvfpfLfCYc7T7aq1Zvezy1CvXFUvTZBG3qTYfb4VXPHHacVNWczKvUSbBTn33d2a5bPmktWKhbWbRyjbgUyCS8KQ1REkQNcaZTMUdLaR8vSVBnHfhd5Tpw4YuKdp5Rn2zLVsHoHTMPRppQTVfECk6hzbzDTMmKB2tXjFGn2FkdH6cfCNwwqViDroKY6T86p7q9Vak5etWqhMmNuNm3cE79xZKUdKgoPd6raVQ7SP8hcsmahFMkoKpfihCj1K65iysVqD4AJtqHUSUcC3ajnYPu4NEXW2txuTYLzdBEYSuMiwvmxYmRSwUYA7np6PuB5pjL8fn56ygSUL2uT6u54ygUeQhcSEEVTtF8VAigKuWTfFGveA6XR4SwjRVZkZ2QviWD516KA1eGosKUc7AEhvrrst4Bar9sBngzv5YcTyZfuh2mZ4hHinqfnnu32eNjwjf2k4EHfTePtR5ajzh15wyy2PruiKLADPZ63WvG2txjuGwD1ZxRm2FzcNwcH2GJuZrQGKruf  Created Time:          Thu, 24 Aug 2023 16:40:36 MDT  Endpoint:              tcp://3.88.69.227:22  Host ID:               hst_7Jeh2Z1mKk  Scope ID:              p_ZWc13Om0sf  Session ID:            s_RilblR6Arw  Target ID:             ttcp_TV3E2bW91i  Type:                  tcp  User ID:               u_r1jtIlLsjK

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 ssh -authz-token="SunS4TVHcdxa8JfJUFWvSwbQfB9Njy6NTnL5ExZYm1k5SpFkVS6RwZfnHuKQnDhDveBzqibAsTb4Wj3jwwBQ2AoruqgRDjXfg4zoU8Y7dkBZCxEzzXt7ii5nLH8HNa7vBxUH95bLR5TkpMMFSVvn9oH4QekDyeiLfNZSBxMFLkhSWhJTrJQpqii6CjLogxQaAJMf5bmtCJBf4YRT3N2FqKdACSM73zHFgb1a5VhMJwbha33yyZ2QzjcWFo3NCv2kaiRjiYL6qjaeaW7hRcA3jm2Cf5tSwdogP4mni4phhKQhRbh4BFNwDNWjWdTDa12ZbxwYcryAgMBPnQgiJQ5gZXL2LKDqPqG6ULx5bsJMtEvPASADSKFKV4esEZMaSoccbtBq63fmvpRPCh8w8QF4iK5jmgrp5j9dYopYRNY1GP5wuKMUnE4SWr52XpiTQqZ35fkYWSTURaxgJ9SqUAikZWXb4ToBUsFG1Yig4pMo7XRvcKwH4Z71QGZus6tYxUzWS2zs2NjXZPFeACpMLfBYEKMsUZ7tbmME6ByqFfdTvtzwkSsXnqtL3nr32fw3TpcG6SqgoaxhfoZXUEsBvsLHNDP7tJLURtrbUsVuFcjRQ9pB51CBd3gQv8HBYQ2m7w1zGPrUzpRfRnLizjbgTsX8n3CcR5NRHau6KyxB45PTKJgXkmNAAVq6D8xLTwz1U8mahdC1SgXoJkfwF6kSaUGzwUHjvunCzTV5NnyGog5cTG4PzhrLHv3V7Z59CdAiPCZxs7DuGodqy6dF2mfj4tQWpFBo" Proxy listening information:  Address:             127.0.0.1  Connection Limit:    -1  Expiration:          Fri, 25 Aug 2023 00:45:56 MDT  Port:                58677  Protocol:            tcp  Session ID:          s_tDBDJCxDnv

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 61135) and note the Address (127.0.0.1).

Open a new terminal window.

Attempt to establish an ssh session to your localhost again. Like before, Remote Login may need to be enabled for the session to connect as expected.

When prompted, enter yes to continue connecting to the host.

$ ssh 127.0.0.1 -p 52185 -l $UBUNTU_USER -i $UBUNTU_KEYThe authenticity of host '[127.0.0.1]:58677 ([127.0.0.1]:58677)' can't be established.ED25519 key fingerprint is SHA256:WDPtMwr4whbVp5VUJwvzee7x9O25XhqMyApnz1mmNfg.This host key is known by the following other names/addresses:    ~/.ssh/known_hosts:9: hst_7jeh2z1mkkAre you sure you want to continue connecting (yes/no/[fingerprint])? yesWarning: Permanently added '[127.0.0.1]:58677' (ED25519) to the list of known hosts. Welcome to Ubuntu 22.04.2 LTS (GNU/Linux 5.19.0-1025-aws x86_64)  * Documentation:  https://help.ubuntu.com * Management:     https://landscape.canonical.com * Support:        https://ubuntu.com/advantage ubuntu@ip-172-32-88-177:~

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 HCP Boundary, check out the Self-Managed Worker Registration tutorial.

Previous

Manage roles and permissions with HCP

 Next

Manage workers with HCP