HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Boundary Home

You are viewing documentation for version v0.10.x. View latest version.

connect-to-target

Connect to Your First Target

The Quick setup wizard is the fastest way to onboard a target to HCP Boundary.

Setup Wizard

A tcp target with a default port of 22 (the default SSH port using TCP) is recommended for an initial target. If using the Quick setup, a sample host set called QA Databases will contain the CRM Database host, with the Address provided during setup. When boundary connect is executed against the CRM Database target, the single available host will be selected and a local authenticated proxy to the host is established on the target's default port.

Setup Wizard

To connect to the initial CRM Database target:

  1. Copy the CRM Database target ID (such as ttcp_eTcZMueUYv).

  2. Open a terminal session. Export the Boundary Origin URL as an environment variable.

$ export BOUNDARY_ADDR=<boundary-origin-url>
  1. Connect to the target.
$ boundary connect -target-id ttcp_eTcZMueUYv

The output displays the address and port that your SSH client must utilize. In the next section the ssh connect 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.

Using Connect Helpers

Boundary includes connect helpers that automatically accept host SSH key prompts for you. These are written as boundary connect <subcommand>.

In the following example, the helper will automatically execute 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.

$ boundary connect ssh -target-id ttcp_eTcZMueUYv

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 will be passed to the executed client. For instance:

$ boundary connect ssh -target-id ttcp_eTcZMueUYv -- -l some-other-user

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 will provide 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.

Selecting 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:

Note however that these are not uniquely identifying, as names can be re-used 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:

$ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope"

Built-In vs. Exec

Boundary comes with built-in wrappers for popular layer 7 connection protocols, such as:

  • ssh: defaults to the local SSH client (ssh)
  • postgres: defaults to the official Postgres CLI client (psql)
  • rdp: defaults to the built-in Windows RDP client (mstsc)
  • http: defaults to curl
  • kube: defaults to kubectl

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 --:

$ boundary connect ssh -target-id ttcp_eTcZMueUYv -- -l myuser -i ~/.ssh/identity

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 that boundary connect has opened.
  • {{boundary.port}} (BOUNDARY_PROXIED_PORT): The port of the listening socket that boundary connect has 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:

$ boundary targets update tcp -default-port 443 -id ttcp_eTcZMueUYv

Target information:
  Created Time:               Fri, 17 June 2022 18:35:47 PDT
  Description:                Sample target created by quick setup
  ID:                         ttcp_eTcZMueUYv
  Name:                       CRM Database target
  Session Connection Limit:   1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Fri, 17 June 2022 19:15:17 PDT
  Version:                    2

  Scope:
    ID:                       p_A4jfDjZ9jf
    Name:                     Sample project created by quick setup
    Parent Scope ID:          o_B1xISmpJ5Y
    Type:                     project

  Host Sets:
    Host Catalog ID:          hcst_YgIU0sHxXp
    ID:                       hsst_pp6f2hfRYB

  Attributes:
    Default Port:             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:

$ boundary connect -exec curl -target-id ttcp_eTcZMueUYv \
         -- -vvsL --output /dev/null hashicorp.com

*   Trying 76.76.21.21...
* TCP_NODELAY set
* Connected to hashicorp.com (76.76.21.21) port 80 (#0)
> GET / HTTP/1.1
> Host: hashicorp.com
> User-Agent: curl/7.64.1
> Accept: */*
...<truncated output>...

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):

$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_eTcZMueUYv

Connect using 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.