• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Boundary
  • Install
  • Tutorials
  • Documentation
  • API
  • Try Cloud(opens in new tab)
  • Sign up
HCP Administration

Skip to main content
8 tutorials
  • Introduction to HCP Boundary
  • Manage Scopes with HCP Boundary
  • Manage Targets with HCP Boundary
  • Manage Users and Groups with HCP Boundary
  • Manage Roles and Permissions with HCP Boundary
  • Manage Sessions with HCP Boundary
  • Self-Managed Worker Registration with HCP Boundary
  • SSH Credential Injection with HCP Boundary

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Boundary
  3. Tutorials
  4. HCP Administration
  5. Manage Sessions with HCP Boundary

Manage Sessions with HCP Boundary

  • 8min

  • HCPHCP
  • BoundaryBoundary

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.

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>
    
  1. Select Projects > QA_Tests Project

  2. Select Targets and copy the ID of the ubuntu target. Project

Now, you have the target ID and host ID.

Start a session

Connect to the ubuntu host on the ubuntu-target target.

When prompted, enter your local administrator user password to proceed.

$ boundary connect ssh -target-id=$TARGET_ID -host-id=$HOST_ID
The authenticity of host 'hst_frdnpd9zm9 ([127.0.0.1]:60309)' can't be established.
ECDSA key fingerprint is SHA256:ZsbEADHGE95YlTkqSoKH+OMLHh//u33yEWs6DuB1DSc.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'hst_frdnpd9zm9' (ECDSA) to the list of known hosts.
Password:
Last login: Wed May 25 10:44:12 2022

On MacOS you might receive an error message similar to No connection could be made because the target machine actively refused it. In this case, you may need to enable Remote Login under the System Preferences -> Sharing settings for your user.

Even with Remote Login enabled, you may need to directly add your username to the list of users under "Allow access for:". Enable "Only these users" and add your username to the list using the + button.

An example of this settings panel is shown below. You may need to add your username instead of "Administrators". After enabling, try running boundary connect ssh again.

MacOS Troubleshooting

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_nUho4KvZcL
    Status:              active
    Created Time:        Fri, 27 May 2022 11:41:41 MDT
    Expiration Time:     Fri, 27 May 2022 19:41:41 MDT
    Updated Time:        Fri, 27 May 2022 11:41:41 MDT
    User ID:             u_1234567890
    Target ID:           ttcp_34yV5O9cwt
    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_uKM9MXIzSg
  Created Time:        Fri, 27 May 2022 11:41:41 MDT
  Endpoint:            tcp://localhost:22
  Expiration Time:     Fri, 27 May 2022 19:41:41 MDT
  Host ID:             hst_FrdNPd9Zm9
  Host Set ID:         hsst_X8gmzYXbO4
  ID:                  s_nUho4KvZcL
  Status:              active
  Target ID:           ttcp_34yV5O9cwt
  Type:                tcp
  Updated Time:        Fri, 27 May 2022 11:41:41 MDT
  User ID:             u_1234567890
  Version:             2

  Scope:
    ID:                p_oMgeFL2hP6
    Name:              QA_Tests
    Parent Scope ID:   o_u54jrD6ydN
    Type:              project

  Authorized Actions:
    no-op
    read
    read:self
    cancel
    cancel:self

  States:
    Start Time:        Fri, 27 May 2022 11:41:41 MDT
    Status:            active

    End Time:          Fri, 27 May 2022 11:41:41 MDT
    Start Time:        Fri, 27 May 2022 11:41:41 MDT
    Status:            pending
  1. Select Projects > QA_Tests Project

  2. Select Sessions to view the list of sessions. Project

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_uKM9MXIzSg
  Created Time:        Fri, 27 May 2022 11:41:41 MDT
  Endpoint:            tcp://localhost:22
  Expiration Time:     Fri, 27 May 2022 19:41:41 MDT
  Host ID:             hst_FrdNPd9Zm9
  Host Set ID:         hsst_X8gmzYXbO4
  ID:                  s_nUho4KvZcL
  Status:              canceling
  Target ID:           ttcp_34yV5O9cwt
  Type:                tcp
  Updated Time:        Fri, 27 May 2022 11:52:24 MDT
  User ID:             u_1234567890
  Version:             3

  Scope:
    ID:                p_oMgeFL2hP6
    Name:              QA_Tests
    Parent Scope ID:   o_u54jrD6ydN
    Type:              project

  Authorized Actions:
    no-op
    read
    read:self
    cancel
    cancel:self

  States:
    Start Time:        Fri, 27 May 2022 11:52:24 MDT
    Status:            canceling

    End Time:          Fri, 27 May 2022 11:52:24 MDT
    Start Time:        Fri, 27 May 2022 11:41:41 MDT
    Status:            active

    End Time:          Fri, 27 May 2022 11:41:41 MDT
    Start Time:        Fri, 27 May 2022 11:41:41 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_nUho4KvZcL

Session information:
  Auth Token ID:        at_uKM9MXIzSg
  Created Time:         Fri, 27 May 2022 11:41:41 MDT
  Endpoint:             tcp://localhost:22
  Expiration Time:      Fri, 27 May 2022 19:41:41 MDT
  Host ID:              hst_FrdNPd9Zm9
  Host Set ID:          hsst_X8gmzYXbO4
  ID:                   s_nUho4KvZcL
  Status:               terminated
  Target ID:            ttcp_34yV5O9cwt
  Termination Reason:   canceled
  Type:                 tcp
  Updated Time:         Fri, 27 May 2022 11:52:26 MDT
  User ID:              u_1234567890
  Version:              5

  Scope:
    ID:                 p_oMgeFL2hP6
    Name:               QA_Tests
    Parent Scope ID:    o_u54jrD6ydN
    Type:               project

  Authorized Actions:
    no-op
    read
    read:self
    cancel
    cancel:self

  States:
    Start Time:         Fri, 27 May 2022 11:52:26 MDT
    Status:             terminated

    End Time:           Fri, 27 May 2022 11:52:26 MDT
    Start Time:         Fri, 27 May 2022 11:52:24 MDT
    Status:             canceling

    End Time:           Fri, 27 May 2022 11:52:24 MDT
    Start Time:         Fri, 27 May 2022 11:41:41 MDT
    Status:             active

    End Time:           Fri, 27 May 2022 11:41:41 MDT
    Start Time:         Fri, 27 May 2022 11:41:41 MDT
    Status:             pending

Click on the Cancel button to cancel a particular session.

Session

The session status becomes canceling and then terminated.

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 authorize token for the ubuntu host.

Example:

$ boundary targets authorize-session -id=$TARGET_ID -host-id=$HOST_ID

Target information:
  Authorization Token:
  SunS4TVHcdxa8JfJUFWvSwbQfB9Njy6NTnL5ExZYm1k5SpFkVS6RwZfnHuKQnDhDveBzqibAsTb4Wj3jwwBQ2AoruqgRDjXfg4zoU8Y7dkBZCxEzzXt7ii5nLH8HNa7vBxUH95bLR5TkpMMFSVvn9oH4QekDyeiLfNZSBxMFLkhSWhJTrJQpqii6CjLogxQaAJMf5bmtCJBf4YRT3N2FqKdACSM73zHFgb1a5VhMJwbha33yyZ2QzjcWFo3NCv2kaiRjiYL6qjaeaW7hRcA3jm2Cf5tSwdogP4mni4phhKQhRbh4BFNwDNWjWdTDa12ZbxwYcryAgMBPnQgiJQ5gZXL2LKDqPqG6ULx5bsJMtEvPASADSKFKV4esEZMaSoccbtBq63fmvpRPCh8w8QF4iK5jmgrp5j9dYopYRNY1GP5wuKMUnE4SWr52XpiTQqZ35fkYWSTURaxgJ9SqUAikZWXb4ToBUsFG1Yig4pMo7XRvcKwH4Z71QGZus6tYxUzWS2zs2NjXZPFeACpMLfBYEKMsUZ7tbmME6ByqFfdTvtzwkSsXnqtL3nr32fw3TpcG6SqgoaxhfoZXUEsBvsLHNDP7tJLURtrbUsVuFcjRQ9pB51CBd3gQv8HBYQ2m7w1zGPrUzpRfRnLizjbgTsX8n3CcR5NRHau6KyxB45PTKJgXkmNAAVq6D8xLTwz1U8mahdC1SgXoJkfwF6kSaUGzwUHjvunCzTV5NnyGog5cTG4PzhrLHv3V7Z59CdAiPCZxs7DuGodqy6dF2mfj4tQWpFBo
  Created Time:          Fri, 27 May 2022 12:12:19 MDT
  Endpoint:              tcp://localhost:22
  Host ID:               hst_FrdNPd9Zm9
  Scope ID:              p_oMgeFL2hP6
  Session ID:            s_fQAyYxqvfF
  Target ID:             ttcp_34yV5O9cwt
  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="SunS4TVHcdxa8JfJUFWvSwbQfB9Njy6NTnL5ExZYm1k5SpFkVS6RwZfnHuKQnDhDveBzqibAsTb4Wj3jwwBQ2AoruqgRDjXfg4zoU8Y7dkBZCxEzzXt7ii5nLH8HNa7vBxUH95bLR5TkpMMFSVvn9oH4QekDyeiLfNZSBxMFLkhSWhJTrJQpqii6CjLogxQaAJMf5bmtCJBf4YRT3N2FqKdACSM73zHFgb1a5VhMJwbha33yyZ2QzjcWFo3NCv2kaiRjiYL6qjaeaW7hRcA3jm2Cf5tSwdogP4mni4phhKQhRbh4BFNwDNWjWdTDa12ZbxwYcryAgMBPnQgiJQ5gZXL2LKDqPqG6ULx5bsJMtEvPASADSKFKV4esEZMaSoccbtBq63fmvpRPCh8w8QF4iK5jmgrp5j9dYopYRNY1GP5wuKMUnE4SWr52XpiTQqZ35fkYWSTURaxgJ9SqUAikZWXb4ToBUsFG1Yig4pMo7XRvcKwH4Z71QGZus6tYxUzWS2zs2NjXZPFeACpMLfBYEKMsUZ7tbmME6ByqFfdTvtzwkSsXnqtL3nr32fw3TpcG6SqgoaxhfoZXUEsBvsLHNDP7tJLURtrbUsVuFcjRQ9pB51CBd3gQv8HBYQ2m7w1zGPrUzpRfRnLizjbgTsX8n3CcR5NRHau6KyxB45PTKJgXkmNAAVq6D8xLTwz1U8mahdC1SgXoJkfwF6kSaUGzwUHjvunCzTV5NnyGog5cTG4PzhrLHv3V7Z59CdAiPCZxs7DuGodqy6dF2mfj4tQWpFBo"

Proxy listening information:
  Address:             127.0.0.1
  Connection Limit:    -1
  Expiration:          Fri, 27 May 2022 20:12:19 MDT
  Port:                61135
  Protocol:            tcp
  Session ID:          s_fQAyYxqvfF

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 your local administrator user password to proceed.

$ ssh 127.0.0.1 -p 52185
The authenticity of host '[127.0.0.1]:61135 ([127.0.0.1]:61135)' can't be established.
ECDSA key fingerprint is SHA256:ZsbEADHGE95YlTkqSoKH+OMLHh//u33yEWs6DuB1DSc.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '[127.0.0.1]:61135' (ECDSA) to the list of known hosts.
Password:
Last login: Fri May 27 12:16:34 2022

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
 Next

On this page

  1. Manage Sessions with HCP Boundary
  2. Prerequisites
  3. Retrieve resource IDs
  4. Start a session
  5. View sessions
  6. Cancel a session
  7. Advanced session establishment
  8. Summary
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)