diff --git a/website/content/docs/getting-started/connect-to-target.mdx b/website/content/docs/getting-started/connect-to-target.mdx index 687be4ced..73e371043 100644 --- a/website/content/docs/getting-started/connect-to-target.mdx +++ b/website/content/docs/getting-started/connect-to-target.mdx @@ -2,32 +2,60 @@ layout: docs page_title: Documentation sidebar_title: Connect to Target -description: Connecting to your first target +description: |- + Connecting to your first target --- # Connect to Your First Target -Make sure you've exported the dev Boundary server address: `export BOUNDARY_ADDR=http://127.0.0.1:9200` - -The default target is a TCP target with a default port of `:22`. The default host associated with this target is `127.0.0.1`. When we run `boundary connect` against this target, we'll open a local authenticated proxy to the target host's default port (`127.0.0.1:22`). Because this target is proxying our SSH server locally, we can use our built-in `connect ssh` command to wrap the proxied TCP connection and SSH via Boundary: +The default target is a TCP target with a default port of `22` (SSH). 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 target host on the target's default port (`127.0.0.1:22`). Because this +target is proxying to our local SSH server, we can use our built-in `connect +ssh` command to wrap the proxied TCP connection and SSH via Boundary: ``` -boundary connect ssh -target-id ttcp_1234567890 -- -l +boundary connect ssh -target-id ttcp_1234567890 ``` -This will execute SSH on the target and port combination specified by the local boundary proxy. The `--` usage allows you to specify flags to pass to the SSH session, in this case, `-l ` allows us to override the username SSH will use in starting the session. +This will execute SSH on the target and port combination specified by the local +boundary proxy. If you want to specify a username other than your currently +logged-in user, you can do so via the `-username` flag. + +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, rather than using +`-username`, an equivalent alternative would be: + +``` +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. ## Built-In vs. Exec -Boundary comes with built-in wrappers for popular layer 7 connection protocols, such as: +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 your local Postgres client (`psql`) -- `rdp`: defaults to your local RDP client (`mstsc`) +- `postgres`: defaults to the official Postgres CLI client (`psql`) +- `rdp`: defaults to the built-in Windows RDP client (`mstsc`) -However, we know that sometimes you may want to do something totally off the cuff, and for that we have a built in connect flag called `-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. +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. -For example, if we wanted to use Boundary to create an authenticated firewall around DNS lookups, we can update the default TCP target from a default port of `:22` to `:53` +For example, if you wanted to use Boundary to create an authenticated firewall +around DNS lookups, you could update the default TCP target from a default port +of `:22` to `:53` ``` boundary targets update tcp -default-port 53 -id ttcp_1234567890 @@ -57,9 +85,10 @@ Target information: Default Port: 53 ``` -We can see in the output above that the default port for our target has now changed to `:53`. +In the output above the default port for the target has now changed to `:53`. -Now, lets also update the default static host's address from `127.0.0.1` to google's DNS server, `8.8.8.8`: +Next, the default static host's address needs to be updated, for example from +`127.0.0.1` to Google's public DNS server `8.8.8.8`: ``` boundary hosts update static -address 8.8.8.8 -id hst_1234567890 @@ -84,11 +113,12 @@ Host information: address: 8.8.8.8 ``` -And finally, lets exec a `dig` command as the wrapper for our TCP target session to do an authenticated DNS query of google.com: +Now, `dig` can be used as the executed client for the TCP target session to do +an authenticated DNS query of google.com: ``` -boundary connect -exec dig -target-id ttcp_1234567890 \ - -- @{{boundary.ip}} \ +boundary connect -exec dig -target-id ttcp_1234567890 -- \ + @{{boundary.ip}} \ -p {{boundary.port}} \ +tcp google.com @@ -102,10 +132,10 @@ boundary connect -exec dig -target-id ttcp_1234567890 \ ;; OPT PSEUDOSECTION: ; EDNS: version: 0, flags:; udp: 512 ;; QUESTION SECTION: -;google.com. IN A +;google.com. IN A ;; ANSWER SECTION: -google.com. 299 IN A 216.58.193.78 +google.com. 299 IN A 216.58.193.78 ;; Query time: 68 msec ;; SERVER: 127.0.0.1#49757(127.0.0.1) @@ -113,6 +143,20 @@ google.com. 299 IN A 216.58.193.78 ;; MSG SIZE rcvd: 55 ``` -In the above example, we override the nameserver with `@{{boundary.ip}}` to tell dig to use the local Boundary proxy IP as the namesever. We also overrode the port dig uses with `-p {{boundary.port}}` to tell dig to use the ephemeral port that Boundary proxy will run the session on. +In the above example, the normal system nameserver is being overridden with +`@{{boundary.ip}}` to tell dig to use the local Boundary proxy IP as the +namesever. The port dig uses has also been overriden with `-p {{boundary.port}}` +to tell dig to use the ephemeral port on which Boundary proxy will run the +session. -Lastly, you'll notice we used the `+tcp` flag for the dig command here. DNS by default will use UDP and the session that Boundary creates is a TCP connection, so we override this to force dig to use TCP by default. +Lastly, the `+tcp` flag was specified for dig, as DNS by +default will use UDP and the session that Boundary creates is a TCP connection. + +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: + +``` +boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890 +``` \ No newline at end of file