Boundary
Connect to your first target
In the Admin Console, the Generated localhost ssh target with an alias has the address 127.0.0.1 with connection type TCP. This is a TCP target with a default port of 22 (SSH). In this tutorial, you will start an ssh session to this default target using the CLI command.
Open a terminal session and set up environment variables to support your Boundary instance.
Note
The use of environment variables is not required, but used for the ease of following this tutorial.
Create an environment variable for the Generated target with an alias ID. Copy the target ID from the Admin Console.
$ export TARGET_ID=ttcp_YennSYsnwU
If you authenticated through the Admin Console UI, authenticate with Boundary using the CLI with the login name admin and password password.
$ boundary authenticate
Please enter the login name (it will be hidden):
Please enter the password (it will be hidden):
Authentication information:
Account ID: acctpw_VOeNSFX8pQ
Auth Method ID: ampw_ZbB6UXpW3B
Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
User ID: u_ogz79sV4sT
The token was successfully stored in the chosen keyring and is not displayed here.
Boundary clusters require an accessible key management service (KMS). An error may occur if this service is not running. If you have any issues check the Troubleshooting section in the Getting Started with Boundary tutorial.
Read the Target Details
Read the details about the Generated localhost ssh target with an alias.
$ boundary targets read -id $TARGET_ID
Target information:
Address: 127.0.0.1
Created Time: Thu, 23 May 2024 17:17:49 MDT
Description: Provides an initial localhost target to SSH to using an alias in
Boundary
ID: ttcp_YennSYsnwU
Name: Generated localhost ssh target with an alias
Session Connection Limit: -1
Session Max Seconds: 28800
Type: tcp
Updated Time: Thu, 23 May 2024 17:17:49 MDT
Version: 1
Scope:
ID: p_1234567890
Name: Generated project scope
Parent Scope ID: o_1234567890
Type: project
Authorized Actions:
set-credential-sources
no-op
update
add-host-sources
authorize-session
delete
remove-host-sources
add-credential-sources
remove-credential-sources
read
set-host-sources
Aliases:
ID: alt_Vvzm43L8oe
Value: ssh.boundary.dev
Attributes:
Default Port: 22
Use the boundary connect command to SSH into the localhost.
$ boundary connect ssh -target-id $TARGET_ID
This will attempt to establish an ssh session to your localhost. You may need to enable Remote Login on your system for the session to connect as expected.
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.
In the terminal where Boundary server is running, you should see connection
successfully authorized message.
{
"id": "C5pFCkDOJC",
"source": "https://hashicorp.com/boundary/AWTMC02DRD6R/controller+worker",
"specversion": "1.0",
"type": "observation",
"data": {
"latency-ms": 52.460987,
"request_info": {
"id": "gtraceid_8Z4m3H9C4Qs453VSMbQG",
"method": "POST",
"path": "/v1/targets/ttcp_YennSYsnwU:authorize-session",
"public_id": "at_FFPNWPkM5c",
"client_ip": "127.0.0.1"
},
"start": "2024-05-23T17:34:12.394394-06:00",
"status": 200,
"stop": "2024-05-23T17:34:12.446855-06:00",
"version": "v0.1"
},
"datacontentype": "text/plain",
"time": "2024-05-23T17:34:12.44688-06:00"
}
{
"id": "t6nOYORm7o",
"source": "https://hashicorp.com/boundary/AWTMC02DRD6R/controller+worker",
"specversion": "1.0",
"type": "system",
"data": {
"version": "v0.1",
"op": "worker.(Worker).handleProxy",
"data": {
"msg": "session successfully activated",
"session_id": "s_TNkyKMwuwM"
}
},
"datacontentype": "text/plain",
"time": "2024-05-23T17:34:12.491546-06:00"
}
{
"id": "prENrL8X62",
"source": "https://hashicorp.com/boundary/AWTMC02DRD6R/controller+worker",
"specversion": "1.0",
"type": "system",
"data": {
"version": "v0.1",
"op": "worker.(Worker).handleProxy",
"data": {
"connection_id": "sc_dhEBpPysQT",
"msg": "connection successfully authorized",
"session_id": "s_TNkyKMwuwM"
}
},
"datacontentype": "text/plain",
"time": "2024-05-23T17:34:12.500967-06:00"
}
Type exit to close the connection to the localhost.
You can connect to a target using an alias instead of an ID.
Read the target details again, and find the Aliases value.
$ boundary targets read -id $TARGET_ID
Target information:
Address: 127.0.0.1
Created Time: Thu, 23 May 2024 17:17:49 MDT
Description: Provides an initial localhost target to SSH to using an alias in
Boundary
ID: ttcp_YennSYsnwU
Name: Generated localhost ssh target with an alias
Session Connection Limit: -1
Session Max Seconds: 28800
Type: tcp
Updated Time: Thu, 23 May 2024 17:17:49 MDT
Version: 1
Scope:
ID: p_1234567890
Name: Generated project scope
Parent Scope ID: o_1234567890
Type: project
Authorized Actions:
set-credential-sources
no-op
update
add-host-sources
authorize-session
delete
remove-host-sources
add-credential-sources
remove-credential-sources
read
set-host-sources
Aliases:
ID: alt_Vvzm43L8oe
Value: ssh.boundary.dev
Attributes:
Default Port: 22
Connect to the target again using the alias ssh.boundary.dev.
$ boundary connect ssh ssh.boundary.dev
If you want to specify a username to login with, you can do so via the
-username flag. For example:
$ boundary connect ssh ssh.boundary.dev -username james
There is also a -style flag to specify a different SSH clients. Currently,
the boundary connect ssh command supports -style putty to support passing
connection information to PuTTY for Windows users.
$ boundary connect ssh -style putty -exec putty.exe ssh.boundary.dev
If you want to pass additional arguments to the SSH client, provide them to the
command line separated by "--" (space, two hyphens, space). Any arguments
after the hyphens are sent directly to the executed client.
For example, the following command accomplishes the same as -username flag.
$ boundary connect ssh ssh.boundary.dev -- -l james
Read the Boundary connect usages section to learn
more about the boundary connect command.
Manage sessions
In the admin console, select Sessions. The UI will show an entry with session
ID matching in the server log (e.g. s_895vskVZh0).
Open a new command terminal and execute the boundary connect command again.
$ boundary connect ssh ssh.boundary.dev
Return to the admin console. You should see two sessions listed.
Click the Cancel button of one of the sessions. The status changes to
canceling and then terminated.
The command terminal where the SSH session was running should also show the connection was closed.
Connection closed by 127.0.0.1 port 53909
In the Boundary server log, you should see a message indicating that the worker terminated the SSH session.
[INFO] worker: terminated connection due to cancelation or expiration: session_id=s_7VCb07G202 connection_id=sc_ph2gtsFAa7
[INFO] controller.worker-handler: connection closed: connection_id=sc_ph2gtsFAa7
[INFO] controller.worker-handler: connection closed: connection_id=sc_ph2gtsFAa7
Boundary connect usages
Build-in commands
Out of the box, Boundary supports the following connection protocols.
| Subcommand | Description |
|---|---|
http | Authorize a session against a target and invoke an HTTP client to connect |
ssh | Authorize a session against a target and invoke an SSH client to connect |
postgres | Authorize a session against a target and invoke a Postgres client (psql) to connect |
rdp | Authorize a session against a target and invoke an RDP client (mstsc) to connect |
Exec command
The boundary connect can execute clients even when there is no built-in
wrapper subcommand for it using -exec. The -exec flag is a very powerful
tool, allowing you to wrap Boundary TCP sessions in your preferred client. You
can use this flag to create an authenticated proxy to almost anything.
If all command flags are followed by "--" (space, two hyphens, space), then
any arguments after that will be sent directly to the client. This can be
specified via the BOUNDARY_CONNECT_EXEC environment variable as well.
Example
cURL can be used to do an authenticated download of hashicorp.com.
First, update the default TCP target (ttcp_1234567890) port from 22 to 443
using the boundary targets update command.
$ boundary targets update tcp -default-port 443 ssh.boundary.dev
Target information:
## ...snip...
Attributes:
Default Port: 443
Now, execute the cURL command using the -exec flag.
$ boundary connect -exec curl ssh.boundary.dev \
-- -vvsL --output /dev/null hashicorp.com
Set session limits
By default, the session max time is set to 8 hours (28800 seconds). You can
overwrite the default to limit the session duration using the boundary targets update command.
Set the max session time to 15 seconds to see how it behaves. Also, set the
default TCP port back to 22 if you modified it to use 443.
$ boundary targets update tcp ssh.boundary.dev \
-default-port 22 \
-session-max-seconds 15
Example Output:
$ boundary targets update tcp ssh.boundary.dev \
-default-port 22 \
-session-max-seconds 15
Target information:
Created Time: Wed, 30 Sep 2020 19:12:57 PDT
Description: Provides an initial target in Boundary
ID: ttcp_1234567890
Name: Generated target
Session Connection Limit: 1
Session Max Seconds: 15
Type: tcp
Updated Time: Wed, 30 Sep 2020 22:29:00 PDT
Version: 3
## ...snip...
Attributes:
Default Port: 22
Run the boundary connect command again to SSH into the localhost.
$ boundary connect ssh ssh.boundary.dev
The session automatically terminates after 15 seconds.
Connection closed by 127.0.0.1 port 61789
Termination information:
Reason: Session has expired
Next steps
You learned the boundary connect command, viewed and managed the SSH sessions.
The next step is to install the Boundary Desktop app, and ensure you can repeat relevant steps in this tutorial related to viewing and managing SSH sessions.