From 860a053ba8b5af8d5a0948c4bf047c624b35ddbc Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Thu, 10 Mar 2022 11:26:48 -0700 Subject: [PATCH] Docs: Update connect-to-target page with target-name example (#1887) * added boundary connect -target-name example * removes some passive and ableist language * Apply suggestions from code review add rewrite suggestions from @hugoamvieira Co-authored-by: Hugo * update Using Connect Helpers copy Co-authored-by: Hugo --- .../getting-started/connect-to-target.mdx | 86 ++++++++++--------- 1 file changed, 45 insertions(+), 41 deletions(-) diff --git a/website/content/docs/getting-started/connect-to-target.mdx b/website/content/docs/getting-started/connect-to-target.mdx index 8469054f7c..9c8407d61c 100644 --- a/website/content/docs/getting-started/connect-to-target.mdx +++ b/website/content/docs/getting-started/connect-to-target.mdx @@ -9,25 +9,25 @@ description: |- 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`). +contain the default host, which has the address `127.0.0.1`. When `boundary +connect` is executed against this target, the single available host will be +selected and a local authenticated proxy to the host is established on the +target's default port (`127.0.0.1:22`). ``` $ 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. +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. -`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 `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 @@ -35,54 +35,58 @@ within the authorized session. When you are finished making connections, simply ### 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 `. 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): +Boundary includes connect helpers that automatically accept host SSH key prompts +for you. These are written as `boundary connect `. + +In the following example, the helper will automatically execute `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. ``` $ 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: +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 +to the executed client. For instance: ``` $ 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. +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, 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. +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. ## 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: +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 +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: + +``` +$ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope" +``` + ## Built-In vs. Exec Boundary comes with built-in wrappers for popular layer 7 connection protocols, @@ -100,8 +104,8 @@ 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 `--`: +Whether using `-exec` or one of the listed helpers, you can pass flags to the +executed command by including them after a double-dash `--`: ``` $ boundary connect ssh -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity @@ -171,8 +175,8 @@ $ boundary connect -exec curl -target-id ttcp_1234567890 \ 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: +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): ``` $ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890 @@ -180,8 +184,8 @@ $ 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. +While using the desktop client, choose the target and connect to retrieve local +proxy details.