are Boundary resources created when connecting to 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
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.
»Retrieve resource IDs
To connect to a target, you need the target ID and host ID to use the
flag. If you are not sure about those IDs, follow the steps in this section;
otherwise, skip to the Start a session section.
List the existing targets under the
$ boundary targets list -scope-id=$PROJECT_ID
Target information: ID: ttcp_xanhXo7TS9 Version: 2 Type: tcp Name: tests Description: Test target
Now, you have the target ID (e.g.
List the host IDs that belong to the host catalog.
$ boundary hosts list -host-catalog-id=$HOST_CATALOG_ID
Host information: ID: hst_0OhAUtkL5T Version: 1 Type: static Name: postgres Description: Postgres host ID: hst_l8I0VY4Gq8 Version: 3 Type: static Name: localhost Description: Localhost for testing
Copy the localhost host ID. In the example output, the ID is
Now, you have the target ID and host ID.
»Start a session
Connect to the
localhost host on the
$ boundary connect ssh -target-id=<target_id> -host-id=<host_id>
$ boundary connect ssh -host-id=hst_l8I0VY4Gq8 -target-id=ttcp_xanhXo7TS9
View all sessions which Boundary has under the QA_Tests project by listing them.
$ boundary sessions list -scope-id=$PROJECT_ID
Session information: ID: s_rSSKa4uGFp Status: active Created Time: Thu, 17 Dec 2020 16:50:47 PST Expiration Time: Fri, 18 Dec 2020 00:50:47 PST Updated Time: Thu, 17 Dec 2020 16:50:47 PST User ID: u_1234567890 Target ID: ttcp_xanhXo7TS9
We can get a more detailed view of a specific session by reading it.
$ boundary sessions read -id=<session_id>
$ boundary sessions read -id=s_rSSKa4uGFp Session information: Auth Token ID: at_8eTYHViTqi Created Time: Thu, 17 Dec 2020 16:50:47 PST Endpoint: tcp://localhost:22 Expiration Time: Fri, 18 Dec 2020 00:50:47 PST Host ID: hst_l8I0VY4Gq8 Host Set ID: hsst_q68hY6ua75 ID: s_rSSKa4uGFp Status: active Target ID: ttcp_xanhXo7TS9 Type: tcp Updated Time: Thu, 17 Dec 2020 16:50:47 PST User ID: u_1234567890 Version: 2 Scope: ID: p_HtkJjpSlic Name: QA_Tests Parent Scope ID: o_hGyyUbrL5i Type: project States: Start Time: Thu, 17 Dec 2020 16:50:47 PST Status: active End Time: Thu, 17 Dec 2020 16:50:47 PST Start Time: Thu, 17 Dec 2020 16:50:47 PST Status: pending
»Cancel a session
When unexpected activity was detected, you can force to cancel the session.
Cancel the session using the session ID you discovered in the previous step.
$ boundary sessions cancel -id=<session_id>
$ boundary sessions cancel -id=s_rSSKa4uGFp Session information: Auth Token ID: at_8eTYHViTqi Created Time: Thu, 17 Dec 2020 16:50:47 PST Endpoint: tcp://localhost:22 Expiration Time: Fri, 18 Dec 2020 00:50:47 PST Host ID: hst_l8I0VY4Gq8 Host Set ID: hsst_q68hY6ua75 ID: s_rSSKa4uGFp Status: canceling Target ID: ttcp_xanhXo7TS9 Type: tcp Updated Time: Thu, 17 Dec 2020 17:43:17 PST User ID: u_1234567890 Version: 3 Scope: ID: Name: QA_Tests Parent Scope ID: o_hGyyUbrL5i Type: project States: Start Time: Thu, 17 Dec 2020 17:43:17 PST Status: canceling ...snipped...
The status is now
canceling. When it completes, the session status will change
States: Start Time: Thu, 17 Dec 2020 17:43:20 PST Status: 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>
$ boundary targets authorize-session -id=ttcp_xanhXo7TS9 -host-id=hst_l8I0VY4Gq8 Target information: Authorization Token: Aqk8eWtFeVKswWoSnVuSXGJKxwr7gR2vUCrsfa3jHmDTk...snipped...DKePSXXeyX Created Time: Thu, 17 Dec 2020 17:55:34 PST Host ID: hst_l8I0VY4Gq8 Scope ID: p_HtkJjpSlic Session ID: s_OM0ELaOKT9 Target ID: ttcp_xanhXo7TS9 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
$ boundary connect -authz-token=<authorization_token>
$ boundary connect -authz-token="Aqk8eWtFeVKswWoSnVuSXGJKxwr..snipped...DKePSXXeyX" Proxy listening information: Address: 127.0.0.1 Connection Limit: -1 Expiration: Fri, 18 Dec 2020 01:55:34 PST Port: 52185 Protocol: tcp Session ID: s_OM0ELaOKT9
With the above address and port information, you can connect to the local proxy and have your tcp traffic sent through the Boundary system.
$ ssh 127.0.0.1 -p 52185 ...
The Manage Scopes tutorial demonstrated
the steps to create a new org (
IT_Support) and a project (
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
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