Manage Sessions with 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.
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.
List the existing targets under the
QA_Testsproject.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:
List the host IDs that belong to the host catalog.
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.
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.
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.
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.
List the available scopes.
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.
We can get a more detailed view of a specific session by reading it.
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.
The status is now canceling. When it completes, the session status will change
to terminated.
Wait a moment, and then read the session details.
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.
For this example, gather the target ID and host ID as demonstrated in the previous tutorials:
List all targets.
Copy the tests target ID.
List all host catalogs.
You created the DevOps host catalog during the Manage Targets with HCP Boundary tutorial.
List and review the available hosts created previously.
Generate an authorize token for the ubuntu host.
Example:
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.
Example:
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.
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.