mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
372 lines
12 KiB
372 lines
12 KiB
---
|
|
layout: docs
|
|
page_title: Connect to your first target
|
|
description: |-
|
|
Connecting to your first target
|
|
---
|
|
|
|
# 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). This target is set up with
|
|
`127.0.0.1` as its address. When you execute `boundary connect` against this
|
|
target, a local authenticated proxy to the address is established on the
|
|
target's default port (`127.0.0.1:22`).
|
|
|
|
```shell-session
|
|
$ boundary connect -target-id ttcp_1234567890
|
|
```
|
|
|
|
There is also a secondary `tcp` target with (`ttcp_0987654321`) which uses host
|
|
sets instead of an address. The host sets for this target contain the default
|
|
host, which has the address 127.0.0.1. When you execute `boundary connect`
|
|
against this target, the single available host will be selected and a local
|
|
authenticated proxy to the host is also established on the target's default port
|
|
(127.0.0.1:22).
|
|
|
|
```shell-session
|
|
boundary connect -target-id ttcp_0987654321
|
|
```
|
|
|
|
For the purpose of this guide, both of these targets accomplish the same goal,
|
|
however they have different purposes. Refer to the
|
|
[domain](/boundary/docs/concepts/domain-model/index) documentation for more information.
|
|
|
|
For the rest of this guide, assume the default is used.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
```shell-session
|
|
$ boundary connect ssh -target-id ttcp_1234567890
|
|
```
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689253766-boundary-ssh-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
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:
|
|
|
|
```shell-session
|
|
$ 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. 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.
|
|
|
|
### 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.
|
|
|
|
```shell-session
|
|
$ boundary connect rdp -target-id ttcp_eTcZMueUYv
|
|
```
|
|
|
|
This command executes the RDP client and establishes the connection through
|
|
Boundary.
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689201572-boundary-rdp-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
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.
|
|
|
|
```shell-session
|
|
$ boundary connect postgres -target-id ttcp_eTcZMueUYv -username admin -dbname postgres
|
|
```
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689253770-boundary-postgres-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
The PostgreSQL helper automatically injects brokered credentials, allowing you
|
|
to access the PostgreSQL instance without knowing the username and password.
|
|
|
|
```shell-session
|
|
$ boundary connect postgres -target-id ttcp_eTcZMueUYv -dbname postgres
|
|
```
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689278343-boundary-passwordless-postgres-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
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.
|
|
|
|
```shell-session
|
|
$ boundary connect http -target-id ttcp_VlpkajEuuf -path '/v1/forecast?latitude=40.7143&longitude=-74.006&daily=precipitation_sum&timezone=America%2FNew_York'
|
|
```
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689278326-boundary-http-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
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`:
|
|
|
|
```shell-session
|
|
$ boundary connect kube -target-id ttcp_Yq0QCUMSe2 -- top node
|
|
```
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1689288553-boundary-kube-connect.mov"
|
|
/>
|
|
</video>
|
|
|
|
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 target
|
|
- `target-scope-id`: The ID of the scope in which the target lives
|
|
- `target-scope-name`: The name of the scope in which the target lives
|
|
|
|
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:
|
|
|
|
```shell-session
|
|
$ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope"
|
|
```
|
|
|
|
## 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 `--`:
|
|
|
|
```shell-session
|
|
$ 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`:
|
|
|
|
```shell-session
|
|
$ boundary targets update tcp -default-port 443 -id ttcp_1234567890
|
|
|
|
Target information:
|
|
Address: 127.0.0.1
|
|
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
|
|
|
|
Scope:
|
|
ID: p_1234567890
|
|
Name: Generated project scope
|
|
Parent Scope ID: o_1234567890
|
|
Type: project
|
|
|
|
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:
|
|
|
|
```shell-session
|
|
$ boundary connect -exec curl -target-id ttcp_1234567890 \
|
|
-- -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):
|
|
|
|
```shell-session
|
|
$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890
|
|
```
|
|
|
|
## Connect using the desktop client
|
|
|
|
While using the desktop client, choose the target and connect to retrieve local
|
|
proxy details.
|
|
|
|
<video
|
|
muted
|
|
playsInline
|
|
autoPlay
|
|
loop
|
|
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
|
>
|
|
<source
|
|
type="video/mp4"
|
|
src="https://www.datocms-assets.com/2885/1613612836-boundary-desktop-clickthrough-connect-target-v1-0-0.mp4"
|
|
/>
|
|
</video>
|
|
|
|
## Next steps
|
|
|
|
See our [basic administration
|
|
workflows](/boundary/tutorials/oss-administration)
|
|
for in depth discussion on managing scopes, targets, identities, and sessions.
|