Connect option docs (#3424)
* docs: add ssh connect helper Really just splits this up into a separate heading. We will add more connect helpers as we go. * docs: add RDP connect helper * docs: add postgres connect helper * docs: add http connect helper * docs: add kube connect helper * docs: remove duplicate mention of helpers * docs: Copy edits to dev-mode topic * docs: Copy edits to hcp topic * docs: Minor copy edits --------- Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
This commit is contained in:
Johan Brandhorst-SatzkornandDan Heath authored and 
GitHub committed
1 parent
39953fe329
commit
28de3d712b
2 files changed
+331
-29
No files matched your search
@@ -54,7 +54,9 @@ within the authorized session. When you are finished making connections, simply
|
||||
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,
|
||||
### 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.
|
||||
@@ -63,8 +65,21 @@ A host key must still be accepted upon first connect.
|
||||
$ 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 will be passed
|
||||
line separated by a double dash; anything after the double dash is passed
|
||||
to the executed client. For instance:
|
||||
|
||||
```shell-session
|
||||
@@ -82,6 +97,150 @@ 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.
|
||||
@@ -105,18 +264,10 @@ $ boundary connect ssh -target-name "Generated target" -target-scope-name "Gener
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
||||
@@ -217,4 +368,4 @@ proxy details.
|
||||
|
||||
See our [basic administration
|
||||
workflows](/boundary/tutorials/oss-administration)
|
||||
for in depth discussion on managing scopes, targets, identities, and sessions.
|
||||
for in depth discussion on managing scopes, targets, identities, and sessions.
|
||||
@@ -57,7 +57,9 @@ within the authorized session. When you are finished making connections, simply
|
||||
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,
|
||||
#### 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.
|
||||
@@ -66,8 +68,21 @@ A host key must still be accepted upon first connect.
|
||||
$ boundary connect ssh -target-id ttcp_eTcZMueUYv
|
||||
```
|
||||
|
||||
<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 will be passed
|
||||
line separated by a double dash; anything after the double dash is passed
|
||||
to the executed client. For instance:
|
||||
|
||||
```shell-session
|
||||
@@ -85,6 +100,150 @@ 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.
|
||||
@@ -108,18 +267,10 @@ $ boundary connect ssh -target-name "Generated target" -target-scope-name "Gener
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user