Connect to Your First Target

The default target is a tcp target with a default port of 22 (which corresponds to the default SSH port using TCP). The host sets for this target contain the default host, which has the address 127.0.0.1. When we run boundary connect against this target, the single available host will be selected and we’ll open a local authenticated proxy to the host on the target’s default port (127.0.0.1:22).

  1. $ boundary connect -target-id ttcp_1234567890
  1. $ boundary connect -target-id ttcp_1234567890

In the output you’ll see the address and port that your SSH client must be told to use. In the next section you’ll see the ssh connect helper in action to make it easier to connect to the target with a client.

boundary connect has a number of options; one notable option is -listen-port to choose the port on which the connect command will listen for an incoming connection. This can be convenient for allowing Boundary to work with applications that allow you to select the address to connect to but not the port, but for many applications there are still some extra hurdles that can exist, which is why we are building out helpers.

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

It can be annoying to keep accepting host SSH key prompts as the port changes, much less having to keep copying and pasting the current port. To make this easier, Boundary includes connect helpers that take care of this work for you. These take the form of boundary connect <subcommand>. In the following example, the helper will automatically execute ssh for you, filling in the local address/port, and setting an expected host ID so that future connections on different automatically-allocated ports don’t complain about the host ID changing (you’ll still need to accept a host key the first time):

  1. $ boundary connect ssh -target-id ttcp_1234567890
  1. $ boundary connect ssh -target-id ttcp_1234567890

If you want to pass additional flags to the SSH client, you can do so by adding them to the command line separated by a double-dash; anything after the double dash will be passed to the executed client. For instance:

  1. $ boundary connect ssh -target-id ttcp_1234567890 -- -l some-other-user
  1. $ boundary connect ssh -target-id ttcp_1234567890 -- -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. At the moment, besides ssh (the default), 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, if you want to specify a username other than your currently logged-in user, you can do so via the -username flag. This will ensure that regardless of whether you use the default ssh style or the putty style, the username is properly passed to the executed client — 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 as that’s a single value and most explicit; 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.

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.

In all cases, whether using -exec or one of the listed helpers, you can pass flags to the executed command by including them after a double-dash --:

  1. $ boundary connect ssh -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity
  1. $ boundary connect ssh -target-id ttcp_1234567890 -- -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:

  1. $ boundary targets update tcp -default-port 443 -id ttcp_1234567890
  3. Target information:
  4.   Created Time:               Fri, 25 Sep 2020 18:35:47 PDT
  5.   Description:                Provides an initial target in Boundary
  6.   ID:                         ttcp_1234567890
  7.   Name:                       Generated target
  8.   Session Connection Limit:   1
  9.   Session Max Seconds:        28800
  10.   Type:                       tcp
  11.   Updated Time:               Fri, 25 Sep 2020 18:36:18 PDT
  12.   Version:                    2
  14.   Scope:
  15.     ID:                       p_1234567890
  16.     Name:                     Generated project scope
  17.     Parent Scope ID:          o_1234567890
  18.     Type:                     project
  20.   Host Sets:
  21.     Host Catalog ID:          hcst_1234567890
  22.     ID:                       hsst_1234567890
  24.   Attributes:
  25.     Default Port:             443
  1. $ boundary targets update tcp -default-port 443 -id ttcp_1234567890
  2. Target information:  Created Time:               Fri, 25 Sep 2020 18:35:47 PDT  Description:                Provides an initial target in Boundary  ID:                         ttcp_1234567890  Name:                       Generated target  Session Connection Limit:   1  Session Max Seconds:        28800  Type:                       tcp  Updated Time:               Fri, 25 Sep 2020 18:36:18 PDT  Version:                    2
  3.   Scope:    ID:                       p_1234567890    Name:                     Generated project scope    Parent Scope ID:          o_1234567890    Type:                     project
  4.   Host Sets:    Host Catalog ID:          hcst_1234567890    ID:                       hsst_1234567890
  5.   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:

  1. $ boundary connect -exec curl -target-id ttcp_1234567890 \
  2.          -- -vvsL --output /dev/null hashicorp.com
  4. *   Trying 76.76.21.21...
  5. * TCP_NODELAY set
  6. * Connected to hashicorp.com (76.76.21.21) port 80 (#0)
  7. > GET / HTTP/1.1
  8. > Host: hashicorp.com
  9. > User-Agent: curl/7.64.1
  10. > Accept: */*
  11. ...<truncated output>...
  1. $ boundary connect -exec curl -target-id ttcp_1234567890 \         -- -vvsL --output /dev/null hashicorp.com
  2. *   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 but while specifying the correct available binary, as WSL must use .exe when invoking Windows binaries:

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

Connect using Desktop Client

While using desktop client, choose target and connect to retrieve local proxy details.

Next Steps

See our basic administration workflows for in depth discussion on managing scopes, targets, identities, and sessions.