HashiConfJoin us for our next online community event 8-11 June (CEST) Register Now

Connect to Your First Target

  • 7 min
  • Products Usedboundary

In the admin console, you saw that localhost was listed as Generated target with connection type, TCP. The default target is a TCP target with a default port of 22 (SSH). In this tutorial, you will initiate an ssh session to this default target using the CLI command.

Open a command terminal, and authenticate with Boundary via CLI if you authenticated only through the admin console.

$ boundary authenticate password -auth-method-id=ampw_1234567890 \
    -login-name=admin -password=password

Example output:

Authentication information:
  Account ID:      apw_BPPNtEX82N
  Auth Method ID:  ampw_1234567890
  Expiration Time: Wed, 14 Oct 2020 18:30:40 PDT
  Token:
  at_6FOC0R3hDG_s1FFYccNfP479aLeEMpbGptDrQyG...snip...
  User ID:         u_1234567890

»Read the Target Details

Read the details about the Generated target by its target ID which is ttcp_1234567890.

$ boundary targets read -id ttcp_1234567890

Target information:
  Created Time:               Wed, 07 Oct 2020 12:53:05 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:               Wed, 07 Oct 2020 12:53:05 PDT
  Version:                    1

  Scope:
    ID:                       p_1234567890
    Name:                     Generated project scope
    Parent Scope ID:          o_1234567890
    Type:                     project

  Host Sets:
    Host Catalog ID:          hcst_1234567890
    ID:                       hsst_1234567890

  Attributes:
    Default Port:             22

Use the boundary connect command to SSH into the localhost.

$ boundary connect ssh -target-id ttcp_1234567890

When prompted, enter the password to proceed.

If you want to specify a username to login with, you can do so via the -username flag. For example:

$ boundary connect ssh -target-id ttcp_1234567890 -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 -target-id ttcp_1234567890

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 that will be sent directly to the executed client.

For example, the following command accomplishes the same as -username flag.

$ boundary connect ssh -target-id ttcp_1234567890 -- -l james

In the terminal where Boundary server is running, you should see session activated message similar to below.

[INFO]  controller.worker-handler: session activated: session_id=s_895vskVZh0 target_id=ttcp_1234567890 user_id=u_1234567890 host_set_id=hsst_1234567890 host_id=hst_1234567890
[INFO]  controller.worker-handler: authorized connection: session_id=s_895vskVZh0 connection_id=sc_k77UBTuOxc connections_left=0
[INFO]  controller.worker-handler: connection established: session_id=s_895vskVZh0 connection_id=sc_k77UBTuOxc client_tcp_address=127.0.0.1 client_tcp_port=53850 endpoint_tcp_address=::1 endpoint_tcp_port=22

»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).

Sessions

Open a new command terminal and execute the boundary connect command again.

$ boundary connect ssh -target-id ttcp_1234567890

Return to the admin console. You should see two sessions listed.

Sessions

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 indicate that 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.

SubcommandDescription
httpAuthorize a session against a target and invoke an HTTP client to connect
sshAuthorize a session against a target and invoke an SSH client to connect
postgresAuthorize a session against a target and invoke a Postgres client (psql) to connect
rdpAuthorize 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 -id ttcp_1234567890

Target information:

  ## ...snip...

  Attributes:
    Default Port:             443

Now, execute the cURL command using the -exec flag.

$ boundary connect -exec curl -target-id ttcp_1234567890 \
     -- -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 -id ttcp_1234567890 \
     -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 -target-id ttcp_1234567890

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 configure and manage targets that your organization wishes to protect. The recommended approach is to use Terraform to codify the Boundary configuration.

HashiCorp
stdin: is not a tty