Connect to your first target
The Quick setup wizard is the fastest way to onboard a target to HCP Boundary.
The Quick setup wizard creates a default tcp target with the port 22 (the default SSH port using TCP).
The target is created with the address 127.0.0.1.
When you execute boundary connect against this target, Boundary establishes a local, authenticated proxy to the address on the target's default port (127.0.0.1:22.)
Connect using the CLI
To connect to the initial EC2 Instances target:
Copy the EC2 Instances target ID (such as
ttcp_ZnHEU9h8qX).Open a terminal session. Export the Boundary Cluster URL as an environment variable.
Connect to the target.
The output displays the address and port that your SSH client must use. In the next section the
sshconnect helper is used to make it easier to connect to the target with a client.
The boundary connect command has a number of notable options, such as
-listen-port to choose the port on which the connect command will listen for
an incoming connection. This is convenient for allowing Boundary to work with
applications that allow you to select the connection address, but not the port.
For many applications there are still some extra hurdles that can exist, which
is why connect helpers can be useful.
The dev-mode default target allows you to make as many connections as you want
within the authorized session. When you are finished making connections, simply
Ctrl-C/Command-C the boundary connect process to shut down the session.
Use connect helpers
Boundary includes connect helpers that automatically accept host SSH key prompts
for you. These are written as boundary connect <subcommand>.
SSH connect helper
In the following example, the helper automatically executes ssh for you,
filling in the local address and port. An expected host ID is set to avoid
warnings on future connections when a different port is allocated automatically.
A host key must still be accepted upon first connect.
If you want to pass additional flags to the SSH client, add them to the command line separated by a double dash; anything after the double dash is passed to the executed client. For instance:
There is also a -style flag to allow the command to format arguments in a
different style expected by different SSH clients. Besides the default ssh,
the boundary connect ssh command supports -style putty to support passing
connection information to PuTTY.
One advantage to styles is that Boundary provides information to the client
in the format that makes sense. For example, the -username flag is used to
specify a username other than your currently logged-in user. This ensures that
regardless of your -style choice, the username is properly passed to the
executed client, and you don't need to figure out the syntax yourself.
RDP connect helper
The RDP helper attempts to decide which RDP client to use
depending on your operating system. On Windows, it uses mstsc.exe. On
Mac, it uses open. Other operating systems are not currently supported.
This command executes the RDP client and establishes the connection through Boundary.
The RDP helper also supports a -style flag to allow you to override the
default RDP client. Recognized styles are mstsc and open.
PostgreSQL connect helper
The PostgreSQL helper executes psql, and passes information such as the username and
database name from the command line.
The PostgreSQL helper automatically injects brokered credentials, allowing you to access the PostgreSQL instance without knowing the username and password.
The helper also supports a -style flag to allow you to override the
default PostgreSQL client. The only recognized style is psql.
HTTP connect helper
The HTTP connect helper executes curl, passing information such as the HTTP path,
method, verb, and others. It can be useful to call API endpoints through the Boundary
proxy. In the example below, we call a weather API endpoint to get the rain forecast for
New York for the next few days.
The HTTP helper supports several flags:
host: Specifies the host value to use, overriding the endpoint address from the session information.method: Specifies the method to use. If you do not set this value, the helper uses the client's default method.path: Specifies a path that is appended to the generated URL.scheme: Specifies the scheme to use. The default is https.
The helper also supports a -style flag to allow you to override the
default HTTP client. The only recognized style is curl.
Kubernetes connect helper
The Kubernetes connect helper executes kubectl by proxying the call through Boundary.
It can be useful to access a Kubernetes cluster that does not publicly expose its API server.
To pass subcommands to kubectl, use -- followed by the command you want to pass. In
this example, we're calling kubectl top node:
The Kubernetes helper supports several flags:
host: Specifies the host value to use, overriding the endpoint address from the session information.scheme: Specifies the scheme to use. The default is https.
The helper also supports a -style flag to allow you to override the
default Kubernetes client. The only recognized style is kubectl.
Select targets
When using boundary connect you must identify the target used for connecting.
Convention in this documentation is to use the target ID because it refers to a
single explicit value, however other flags are supported:
target-name: The name of the targettarget-scope-id: The ID of the scope in which the target livestarget-scope-name: The name of the scope in which the target lives
Note however that these are not uniquely identifying, as names can be reused across scopes. As a result, when not using the target ID, you must use the target's name in conjunction with the scope name or scope ID so that Boundary can correctly identify the desired target.
Here is an SSH example in dev-mode:
Built-in vs. exec
We've seen the built-in connect helpers above, however, boundary connect
can accommodate executing clients even when there is no built-in support
for a specific client 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.
Whether using -exec or one of the listed helpers, you can pass flags to the
executed command by including them after a double-dash --:
You also have access to some templated values that are substituted into the command arguments, and these values are additionally injected as environment variables in the executed command:
{{boundary.ip}}(BOUNDARY_PROXIED_IP): The IP address of the listening socket thatboundary connecthas opened.{{boundary.port}}(BOUNDARY_PROXIED_PORT): The port of the listening socket thatboundary connecthas opened.{{boundary.addr}}(BOUNDARY_PROXIED_ADDR): The host:port format of the address. This is essentially equivalent to{{boundary.ip}}:{{boundary.port}}.
For example, if you wanted to use Boundary to create an authenticated firewall
around 'curl', you could update the default TCP target from a default port
of :22 to :443:
In the output above the default port for the target has now changed to :443.
Now, curl can be used as the executed client for the TCP target session to do
an authenticated download of hashicorp.com:
Note that -exec is available for subcommands that wrap clients as well. As an
example, if putty.exe is available on a Windows host but the command is being
run from WSL, the following allows usage of the wrapper while specifying the
correct available binary (as WSL must use .exe when invoking Windows binaries):
Connect using the desktop client
While using the desktop client, choose the target and connect to retrieve local proxy details.
Tutorial
Refer to the Connect to your First Target tutorial for steps on how to create a host catalog, host set, and a target in Boundary.
Next steps
Refer to our basic administration workflows tutorial series for in depth discussions on managing scopes, targets, identities, and sessions.