diff --git a/website/content/docs/common-workflows/workflow-ssh-proxycommand.mdx b/website/content/docs/common-workflows/workflow-ssh-proxycommand.mdx deleted file mode 100644 index 502534c6d..000000000 --- a/website/content/docs/common-workflows/workflow-ssh-proxycommand.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -layout: docs -page_title: SSH ProxyCommand Workflow -description: How to manage SSH proxy configuration with Boundary ---- - -# SSH ProxyCommand Workflow - -The most common pattern for using Boundary to SSH is with the built-in `boundary connect ssh` command. However, -there are more idiomatic approaches that can be employed to make Boundary transparent to users, and at the same -time simplify common developer and operator workflows. Using `ProxyCommand` to execute a proxy when invoking the -SSH client is a common practice. In this workflow, we'll cover configuring your SSH client to execute the -`boundary` command, enabling a simplified SSH workflow that leverages Boundary's authenticated proxy for accessing -targets. - -## SSH Configuration - -Start by configuring a `Host` entry in `.ssh/ssh_config` for `localhost`: - -```bash -Host ttcp_* - ProxyCommand sh -c "boundary connect -target-id %n -exec nc -- {{boundary.ip}} {{boundary.port}}" -``` - -The `ProxyCommand` tells the SSH client to invoke `boundary connect`. We are passing the `-exec nc` flag to -`boundary connect` to wrap [netcat](http://netcat.sourceforge.net/), and then pass the `boundary.ip` and `boundary.port` -variables as arguments to `nc`. This allows us to proxy our SSH connection through a local netcat tunnel that's -managed as a Boundary session. - -When you run `ssh ttcp_1234567890` (example target ID), SSH will invoke `boundary connect`, and will tunnel the traffic through -the local Boundary proxy in a wrapped netcat session, passing in the target ID as the hostname to the `boundary` command. - -## Authenticate to Boundary - -Before `ssh` can invoke `boundary connect` you need to authenticate. In this example, we're using `boundary dev` with the -default username (admin) and password (password), and because this auth method is the primary that resides in the global -scope, we can use the short form of the authenticate command with no extra flags: - -```bash -$ boundary authenticate -``` - -## SSH to Target - -Running Boundary in [dev mode](/boundary/docs/oss/installing/dev-mode) creates other -default resources such as a target and auth method. The default target (ttcp_1234567890) is already setup with a host -at `localhost` and a default port of `22`. - -You can simply run `ssh` as you normally would and all the traffic will be proxied over the Boundary proxy to your target machine: - -```bash -$ ssh ttcp_1234567890 -Password: -Last login: Thu Nov 19 10:32:09 2020 -➜ ~ -``` - -On the controller, you should see the session being invoked in the logs: - -```bash -controller.worker-handler: connection established: session_id=s_WkaQbqmrJx connection_id=sc_RDYNFFI2M4 client_tcp_address=127.0.0.1 client_tcp_port=57421 endpoint_tcp_address=::1 endpoint_tcp_port=22 -``` - -You can inspect the session on the CLI as well: - -```bash -$ boundary sessions read -id $(boundary sessions list -scope-id p_1234567890 -format json | jq '.[0]["id"]' | tr -d '"') - -Session information: - Auth Token ID: at_a8itRfDSyV - Created Time: Thu, 19 Nov 2020 10:52:44 PST - Endpoint: tcp://localhost:22 - Expiration Time: Thu, 19 Nov 2020 18:52:44 PST - Host ID: hst_1234567890 - Host Set ID: hsst_1234567890 - ID: s_WkaQbqmrJx - Status: active - Target ID: ttcp_1234567890 - Type: tcp - Updated Time: Thu, 19 Nov 2020 10:52:47 PST - User ID: u_1234567890 - Version: 2 - - Scope: - ID: p_1234567890 - Name: Generated project scope - Parent Scope ID: o_1234567890 - Type: project - - States: - Start Time: Thu, 19 Nov 2020 10:52:47 PST - Status: active - - End Time: Thu, 19 Nov 2020 10:52:47 PST - Start Time: Thu, 19 Nov 2020 10:52:44 PST - Status: pending -``` - -# Advanced Usage - -Another way to access targets using ProxyCommand is by setting the `Host` value to the target domain instead of the target ID. -This is useful if you want to use the domain name instead of the target ID when forking SSH. An extra step is required to make this -work where you must authorize the session to the target and store it in your environment since we're no longer passing the target -ID to the SSH command. This will allow Boundary to pull the target information from the token you created in the `authorize session` -command. - -## Configure SSH - -```bash -Host localhost - # requires BOUNDARY_CONNECT_AUTHZ_TOKEN to be set from authorize-session command - ProxyCommand sh -c "boundary connect -exec nc -- {{boundary.ip}} {{boundary.port}}" -``` - -## Authenticate to Boundary - -Before `ssh` can invoke `boundary connect` you need to authenticate. In this example, we're using `boundary dev` with the -default username (admin) and password (password): - -```bash -$ boundary authenticate -``` - -## Authorize the Session - -Running Boundary in [dev mode](/boundary/docs/oss/installing/dev-mode) creates other -default resources such as a target and auth method. The default target (ttcp_1234567890) is already setup with a host -at `localhost` and a default port of `22`. - -Authorize a session to the default target and store the token in the `BOUNDARY_CONNECT_AUTHZ_TOKEN` environment variable. -This will be used by Boundary when it's invoked by SSH: - -```bash -$ export BOUNDARY_CONNECT_AUTHZ_TOKEN=$(boundary targets authorize-session -id ttcp_1234567890 -format json | jq '.authorization_token' | tr -d '"') -``` - -## SSH to Target - -```bash -$ ssh user@localhost -Password: -Last login: Thu Nov 19 10:32:09 2020 -➜ ~ -``` diff --git a/website/content/docs/concepts/connection-workflows/connect-helpers.mdx b/website/content/docs/concepts/connection-workflows/connect-helpers.mdx new file mode 100644 index 000000000..a1611f0b0 --- /dev/null +++ b/website/content/docs/concepts/connection-workflows/connect-helpers.mdx @@ -0,0 +1,223 @@ +--- +layout: docs +page_title: Connect helpers +description: Learn how connect helpers enable Boundary to automatically accept host key prompts to facilitate connections for HTTP, Kubernetes, PostgreSQL, RDP, and SSH. +--- + +# Connect helpers + +Boundary includes connect helpers that automatically accept host key prompts for you to help facilitate connections. +These are written as `boundary connect ` and are supported for the following connection types: + +- HTTP +- Kubernetes +- PostgreSQL +- RDP +- SSH + +If you want to pass additional flags to the client, you can add them to the command line separated by a double dash. +Boundary passes anything after the double dash to the executed client. +For example, the following command uses the SSH connect helper to pass `-l some-other-user` to the SSH client: + +```shell-session +$ boundary connect ssh -target-id ttcp_1234567890 -- -l some-other-user +``` + +Connect helpers also support a `-style` flag that lets you override the default client and format arguments in a different style. +For example, besides the default style `ssh`, the SSH connect helper supports a `-style putty` option that lets you pass connection information to PuTTY. + +One advantage to styles is that Boundary can provide information to the client in a format that makes sense. +For example, the `-username` flag is used to specify a username other than the currently logged-in user. +This ensures that regardless of the `-style` you choose, the username is properly passed to the executed client, and you don't have to figure out the syntax for yourself. + +## HTTP connect helper + +The HTTP connect helper executes `curl`, and passes information such as the HTTP path, method, and verb. +It can be useful to call API endpoints through the Boundary proxy. + +The following example calls a weather API endpoint to get the rain forecast for New York: + +```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' +``` + + + +The HTTP helper supports the following flags: + +- `host`: Specifies the host value to use, and overrides 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 Boundary appends to the generated URL. +- `scheme`: Specifies the scheme to use. +The default scheme is `https`. +- `style`: Specifies how the CLI attempts to invoke an HTTP client. +The only supported style for the HTTP helper is `curl`. + +For more information, refer to the [`connect http` command documenatation](/boundary/docs/commands/connect/http). + +## 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. +The following example calls `kubectl top node`: + +```shell-session +$ boundary connect kube -target-id ttcp_Yq0QCUMSe2 -- top node +``` + + + +The Kubernetes helper supports the following flags: + +- `host`: Specifies the host value to use, and overrides the endpoint address from the session information. +- `scheme`: Specifies the scheme to use. +The default scheme is `https`. +- `style`: Specifies how the CLI attempts to invoke a Kubernetes client. +The only supported style for the Kubernetes helper is `kubectl`. + +For more information, refer to the [`connect kube` command documenatation](/boundary/docs/commands/connect/kube). + +## PostgreSQL connect helper + +The PostgreSQL helper executes `psql`, and passes information such as the username and database name from the command line. + +The following example connects to a PostgreSQL database named `boundary`: + +```shell-session +$ boundary connect postgres -target-id ttcp_eTcZMueUYv -username admin -dbname postgres +``` + + + +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 +``` + + + +The PostgreSQL helper supports the following flags: + +- `dbname`: Specifies the database name you want to pass through to the client. +- `style`: Specifies how the CLI attempts to inovke a PostgreSQL client. +The only supported style for the PostgreSQL helper is `psql`. +- `username`: Specifies the username you want to pass through to the client. + +For more information, refer to the [`connect postgres` command documenatation](/boundary/docs/commands/connect/postgres). + +## RDP connect helper + +The RDP helper determines 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. + +The following command executes the RDP client and establishes the connection through Boundary: + +```shell-session +$ boundary connect rdp -target-id ttcp_eTcZMueUYv +``` + + + +The RDP helper supports the following flag: + +- `style`: Specifies how the CLI attempts to inovke an RDP client. +The RDP helper supports the styles `mstsc` and `open`. + +For more information, refer to the [`connect rdp` command documenatation](/boundary/docs/commands/connect/rdp). + +## SSH connect helper + +The SSH helper automatically executes SSH and passes connection information. +An expected host ID is set to avoid warnings on future connections when a different port is allocated automatically. +You must still accept a host key upon the first connection. + +The following command connects to a target and automatically fills in the local address and port: + +```shell-session +$ boundary connect ssh -target-id ttcp_1234567890 +``` + + + +The SSH helper supports the following flags: + +- `remote-command`: Specifies a command you want to run on the remote host. +You can specify a complete command line, or you may include additonal arguments. +If you include additional arguments, you must append them to the command and separate them using spaces. +- `style`: Specifies how the CLI attempts to inovke an SSH client. +The SSH helper supports the styles `ssh` and `putty`. +- `username`: Specifies the username you want to pass through to the client. + +For more information, refer to the [`connect ssh` command documenatation](/boundary/docs/commands/connect/ssh). \ No newline at end of file diff --git a/website/content/docs/concepts/connection-workflows/exec-flag.mdx b/website/content/docs/concepts/connection-workflows/exec-flag.mdx new file mode 100644 index 000000000..4593a1b1c --- /dev/null +++ b/website/content/docs/concepts/connection-workflows/exec-flag.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: -exec flag +description: |- + Learn how the `-exec` flag enables you to execute Boundary TCP sessions using your preferred client, even when there is no built-in support for it. +--- + +# Exec flag + +Boundary includes built-in connect helpers for clients, however, `boundary connect` can execute clients even when there is no built-in support for a specific client using the `-exec` flag. +The `-exec` flag lets you wrap Boundary TCP sessions in your preferred client. +You can use this flag to create an authenticated proxy to almost anything. + +When you use `-exec`, you can pass flags to the client by including them in the executed command after a double-dash `--`. +For example, the following command passes `-l myuser -i ~/.ssh/identity` to the PuTTY client: + +```shell-session +$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity +``` + +You can substitute the following templated values into the command arguments. +Boundary injects these values in the executed command as environment variables: + +- `{{boundary.ip}}` (`BOUNDARY_PROXIED_IP`): The IP address of the listening socket that `boundary connect` 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 value 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` using the following command: + +```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, you can use `curl` as the client for a TCP target session. +For example, the following command uses `curl` to perform 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: */* +...... +``` + +Note that you can use `-exec` 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, you could use the following command to specify the correct binary to use, since WSL must use `.exe` when it invokes Windows binaries: + +```shell-session +$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890 +``` \ No newline at end of file diff --git a/website/content/docs/concepts/connection-workflows/index.mdx b/website/content/docs/concepts/connection-workflows/index.mdx new file mode 100644 index 000000000..cef6aa4e6 --- /dev/null +++ b/website/content/docs/concepts/connection-workflows/index.mdx @@ -0,0 +1,68 @@ +--- +layout: docs +page_title: Connection workflows +description: |- + Workflows that you can use to connect to targets. Learn how connect helpers, the `-exec` flag, and SSH ProxyCommand can help facilitate connections to targets. +--- + +# Connection workflows + +This topic provides an overview of the possible workflows you may use to connect to targets with Boundary. + +## Boundary connect + +When you run the `boundary connect` command against a target, Boundary establishes a local authenticated proxy to the address on the target's default port. +The `boundary connect` command has a number of useful options, such as `-listen-port` which lets you choose the port on which the command listens for an incoming connection. +Refer to the [`boundary connect`](/boundary/docs/commands/connect) documentation for a list of the available options and usage examples. + +To practice using the `boundary connect` command in a development environment, refer to the **Connect to your first target** tutorial for either [HCP Boundary](/boundary/tutorials/hcp-getting-started/hcp-getting-started-connect) or the [self-managed versions](/boundary/tutorials/oss-getting-started/oss-getting-started-connect) of Boundary. + +## Connect helpers + +Boundary features connect helpers that assist with making connections to targets using certain protocols. +Connect helpers automatically accept key prompts for you. +They are supported for the following connection types: + +- HTTP +- Kubernetes +- PostgreSQL +- RDP +- SSH + +Refer to the [Connect helpers](/boundary/docs/concepts/connection-workflows/connect-helpers) documentation for more information. + +## Exec flag + +In addition to the built-in connect helpers, `boundary connect` can accommodate executing clients even when there is no built-in support for a specific client using the `-exec` flag. +The `-exec` flag lets you wrap Boundary TCP sessions in your preferred client. +You can use this flag to create an authenticated proxy to almost anything. + +Refer to the [Exec flag](/boundary/docs/concepts/connection-workflows/exec-flag) documentation for more information. + +## SSH ProxyCommand + +The most common pattern for using Boundary to SSH is with the built-in `boundary connect ssh` command. +However, there are more idiomatic approaches that can be employed to make Boundary transparent to users, and at the same time simplify common developer and operator workflows. +Using `ProxyCommand` to execute a proxy when invoking the SSH client is a common practice. + +SSH `ProxyCommand` lets you proxy an SSH connection to a target according to a configuration file that you create. +You can configure the file to connect to the target ID or the target domain. + +Refer to the [SSH ProxyCommand](/boundary/docs/concepts/connection-workflows/workflow-ssh-proxycommand) documentation for more information. + +## Multi-hop sessions + +This feature requires HCP Boundary or Boundary Enterprise + +Most organizations want to provide access to infrastructure without exposing private networks. +Many organizations also have complex network topologies requiring inbound traffic to route through multiple network enclaves to reach the target system. +Multi-hop sessions allow you to chain together two or more workers across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies. + +You can deploy multi-hop workers in scenarios where inbound network traffic is +not allowed. +A worker in a private network can send outbound communication to its upstream worker, and create a reverse proxy to establish a session. + +You can configure target worker filters with multi-hop workers to allow for fine-grained control on which workers handle ingress and egress for session traffic to a target. +Ingress worker filters determine which workers you connect with to initiate a session, and egress worker filters determine which workers are used to access targets. + +Refer to the [Multi-hop sessions](/boundary/docs/concepts/connection-workflows/multi-hop) documentation for more information. \ No newline at end of file diff --git a/website/content/docs/concepts/connection-workflows/multi-hop.mdx b/website/content/docs/concepts/connection-workflows/multi-hop.mdx new file mode 100644 index 000000000..8b1f0da83 --- /dev/null +++ b/website/content/docs/concepts/connection-workflows/multi-hop.mdx @@ -0,0 +1,87 @@ +--- +layout: docs +page_title: Multi-hop sessions +description: |- + Learn how multi-hop sessions enable you to chain together two or more Boundary workers across multiple networks. +--- + +# Multi-hop sessions + +This feature requires HCP Boundary or Boundary Enterprise + +Most organizations want to provide access to infrastructure without exposing private networks. Many organizations also have complex network topologies requiring +inbound traffic to route through multiple network enclaves to reach the target system. +Multi-hop sessions allow you to chain together two or more workers +across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies. + +In multi-hop scenarios, there are typically three types of workers: +1. **Ingress worker** - An ingress worker is a worker that is accessible by the client. The client initiates the connection to the ingress worker. +1. **Intermediary worker** - An optional intermediary worker sits between ingress and egress workers as part of a multi-hop chain. There can be multiple intermediary workers as part of a multi-hop chain. +1. **Egress worker** - An egress worker is a worker that can access the target. The egress worker initiates reverse proxy connections to intermediary or ingress workers. + + +“Ingress,” “intermediary,” and “egress” are general ways to describe how the respective worker interfaces with resources, and a worker can act as more than one of those +at a time. For example in the diagram below, the intermediary worker is also an egress worker since it can access a target. + + +![Multi-hop session example showing ingress, intermediary, and egress workers](/img/concepts-multihop.png) + +After the persistent connection chain is established between the workers, when you attempt to connect to a target host, you are automatically proxied from: +1. Boundary client to ingress worker +1. Ingress worker to intermediary worker, where applicable +1. Ingress worker to egress worker +1. Egress worker to desired target + +## Multi-hop worker capabilities + +Multi-hop capabilities, including multi-hop sessions and Vault private access, +is when a session or Vault credential request goes through more than one worker. +To enable this, two or more workers must be connected to each other in some +configuration. There are no limits on the number of workers allowed in a +multi-hop session configuration. + +It helps to think of “upstream” and “downstream” nodes in the context of +multi-hop. If you view controllers as the “top” node of a multi-hop chain, any +worker connected to a node is "downstream" of that node; the node that any +particular worker connects to (whether another worker or a controller) is the +"upstream" of that node. For example, in the diagram below, Worker 2’s upstream +is Worker 1, and its downstream is Worker 3. + +![multi-hop workers](/img/multi-hop-workers.png) + +You can deploy multi-hop workers in scenarios where inbound network traffic is +not allowed. A worker in a private network can send outbound communication to +its upstream worker, and create a reverse proxy to establish a session. + +You can configure target worker filters with multi-hop workers to allow for +fine-grained control on which workers handle ingress and egress for session +traffic to a target. Ingress worker filters determine which workers you +connect with to initiate a session, and egress worker filters determine which +workers are used to access targets. + +## Multi-hop worker requirements + +When you configure multi-hop sessions, there is an "ingress" worker, an "egress" +worker, and any number of intermediary workers. Ingress, egress, and +intermediary workers have the following requirements. + +### Ingress worker requirements + +To proxy target connections, ingress workers require outbound access to the +Boundary control plane and inbound access from clients. + +### Intermediary worker requirements + +Intermediary workers require outbound access to an upstream worker. The upstream +worker may be an ingress worker or another intermediary worker. Intermediary +workers also require inbound access from a downstream worker. The downstream +worker may be an egress worker or another intermediary worker. + +### Egress worker requirements + +To proxy target connections, egress workers require outbound access to an +upstream worker and outbound access to the destination host or service. + +## Complete worker configuration + +For the full set of worker parameters and a complete configuration example, refer to the [worker stanza](/boundary/docs/configuration/worker) documentation. \ No newline at end of file diff --git a/website/content/docs/concepts/connection-workflows/workflow-ssh-proxycommand.mdx b/website/content/docs/concepts/connection-workflows/workflow-ssh-proxycommand.mdx new file mode 100644 index 000000000..0823c4726 --- /dev/null +++ b/website/content/docs/concepts/connection-workflows/workflow-ssh-proxycommand.mdx @@ -0,0 +1,136 @@ +--- +layout: docs +page_title: SSH ProxyCommand +description: Learn how SSH ProxyCommand enables you to proxy an SSH connection in Boundary using a configuration file. Configure connections using the target's ID or domain. +--- + +# SSH ProxyCommand + +SSH `ProxyCommand` lets you proxy an SSH connection to a target to simplify common developer and operator workflows. +For example, you can configure the `.ssh/ssh_config` file to connect to the target ID or the target domain. + +## Configure a host using target ID + +To use SSH `ProxyCommand`, you must configure a `Host` entry in `.ssh/ssh_config` for `localhost`. + +In the following example, `ProxyCommand` configures the SSH client to invoke `boundary connect`. + +The command passes the `-exec nc` flag to `boundary connect` to wrap [netcat](http://netcat.sourceforge.net/), and then pass the `boundary.ip` and `boundary.port` environment variables as arguments to `nc`. +This command allows you to proxy your SSH connection through a local netcat tunnel that's managed as a Boundary session: + + + +```bash +Host ttcp_* + ProxyCommand sh -c "boundary connect -target-id %n -exec nc -- {{boundary.ip}} {{boundary.port}}" +``` + + + +Using this configuration, if you run `ssh ttcp_1234567890` to connect to a target with the ID `ttcp_1234567890`, SSH invokes `boundary connect`, and tunnels the traffic through the local Boundary proxy in a wrapped netcat session. +Boundary passes the target ID to the `boundary` command as the hostname. + +Note that you must authenticate to Boundary before you can use `ssh` to invoke `boundary connect`. + +### SSH to target + +Once the command is configured, you can run `ssh` as you normally would and all the traffic is proxied over the Boundary proxy to your target machine: + +```bash +$ ssh ttcp_1234567890 +Password: +Last login: Thu Nov 19 10:32:09 2023 +➜ ~ +``` + +On the controller, you can see the session being invoked in the logs: + +```bash +controller.worker-handler: connection established: session_id=s_WkaQbqmrJx connection_id=sc_RDYNFFI2M4 client_tcp_address=127.0.0.1 client_tcp_port=57421 endpoint_tcp_address=::1 endpoint_tcp_port=22 +``` + +You can inspect the session on the CLI as well: + +```bash +$ boundary sessions read -id $(boundary sessions list -scope-id p_1234567890 -format json | jq '.[0]["id"]' | tr -d '"') + +Session information: + Auth Token ID: at_a8itRfDSyV + Created Time: Thu, 19 Nov 2023 10:52:44 PST + Endpoint: tcp://localhost:22 + Expiration Time: Thu, 19 Nov 2023 18:52:44 PST + Host ID: hst_1234567890 + Host Set ID: hsst_1234567890 + ID: s_WkaQbqmrJx + Status: active + Target ID: ttcp_1234567890 + Type: tcp + Updated Time: Thu, 19 Nov 2023 10:52:47 PST + User ID: u_1234567890 + Version: 2 + + Scope: + ID: p_1234567890 + Name: Generated project scope + Parent Scope ID: o_1234567890 + Type: project + + States: + Start Time: Thu, 19 Nov 2023 10:52:47 PST + Status: active + + End Time: Thu, 19 Nov 2023 10:52:47 PST + Start Time: Thu, 19 Nov 2023 10:52:44 PST + Status: pending +``` + +## Configure a host using target domain + +If you want to use the domain name to SSH to targets, you can set the `Host` value to the target domain instead of the target ID. + +This method requires an extra step. +You must authorize the session to the target and store it in your environment, since you do not pass the target ID as part of the SSH command. +Authorizing the session allows Boundary to pull the target information from the token you create using the `authorize session` command. + +### Authorize the session + +The following example authorizes a session to a target `ttcp_1234567890` and stores the token in the `BOUNDARY_CONNECT_AUTHZ_TOKEN` environment variable. +Boundary uses the token when it's invoked by SSH: + +```bash +$ export BOUNDARY_CONNECT_AUTHZ_TOKEN=$(boundary targets authorize-session -id ttcp_1234567890 -format json | jq '.authorization_token' | tr -d '"') +``` +### Configure the host + +To use SSH `ProxyCommand`, you must configure a `Host` entry in `.ssh/ssh_config` for `localhost`. + +In the following example, `ProxyCommand` configures the SSH client to invoke `boundary connect`. + +The command passes the `-exec nc` flag to `boundary connect` to wrap [netcat](http://netcat.sourceforge.net/), and then pass the `boundary.ip` and `boundary.port` environment variables as arguments to `nc`. +This command allows you to proxy your SSH connection through a local netcat tunnel that's managed as a Boundary session: + + + +```bash +Host localhost + # requires BOUNDARY_CONNECT_AUTHZ_TOKEN to be set from authorize-session command + ProxyCommand sh -c "boundary connect -exec nc -- {{boundary.ip}} {{boundary.port}}" +``` + + + +Using this configuration, if you run `ssh user@localhost` to connect to the target you created the authorization session for, SSH invokes `boundary connect`, and tunnels the traffic through the local Boundary proxy in a wrapped netcat session. +Boundary passes the target domain to the `boundary` command as the hostname. + +Note that you must authenticate to Boundary before you can use `ssh` to invoke `boundary connect`. + +### SSH to target + +Once the command is configured, you can run `ssh` as you normally would and all the traffic is proxied over the Boundary proxy to your target machine: + +```bash +$ ssh user@localhost +Password: +Last login: Thu Nov 19 10:32:09 2023 +➜ ~ +``` diff --git a/website/content/docs/concepts/workers.mdx b/website/content/docs/concepts/workers.mdx index 8758b95d8..c7550939c 100644 --- a/website/content/docs/concepts/workers.mdx +++ b/website/content/docs/concepts/workers.mdx @@ -58,26 +58,9 @@ with tag “A,” to connect to targets in “Network A.” Most organizations want to provide access to infrastructure without exposing private networks. Many organizations also have complex network topologies requiring inbound traffic to route through multiple network enclaves in order to reach the target system. -[Multi-hop](/boundary/docs/configuration/worker#multi-hop-worker-capabilities) sessions allow you to chain together two or more workers -across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies. +Multi-hop sessions allow you to chain together two or more workers across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies. -In multi-hop scenarios, there are typically three types of workers: -1. **Ingress worker** - An ingress worker is a worker that is accessible by the client. The client initiates the connection to the ingress worker. -1. **Intermediary worker** - An optional intermediary worker sits between ingress and egress workers as part of a multi-hop chain. There can be multiple intermediary workers as part of a multi-hop chain. -1. **Egress worker** - An egress worker is a worker that can access the target. The egress worker initiates reverse proxy connections to intermediary or ingress workers. - - -“Ingress,” “intermediary,” and “egress” are general ways to describe how the respective worker interfaces with resources, and a worker can act as more than one of those -at a time. For example in the diagram below, the intermediary worker is also an egress worker since it can access a target. - - -![Multi-hop session example showing ingress, intermediary, and egress workers](/img/concepts-multihop.png) - -After the persistent connection chain is established between the workers, when you attempt to connect to a target host, you are automatically proxied from: -1. Boundary client to ingress worker -1. Ingress worker to intermediary worker, where applicable -1. Ingress worker to egress worker -1. Egress worker to desired target +Refer to the [multi-hop sessions](/boundary/docs/concepts/connection-workflows/multi-hop) documentation for more information. ## Deployment Workers are services that can run on a container or virtual machine. You should deploy them strategically within networks to provide access to targets. In diff --git a/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx index 583739e06..6c0ec219e 100644 --- a/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx +++ b/website/content/docs/getting-started/dev-mode/connect-to-dev-target.mdx @@ -49,198 +49,6 @@ 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 `. - -### 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 -``` - - - -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. - - - -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 -``` - - - -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 -``` - - - -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' -``` - - - -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 -``` - - - -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. @@ -262,91 +70,40 @@ Here is an SSH example in dev mode: $ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope" ``` +## Connect helpers + +Boundary includes connect helpers that automatically accept host SSH key prompts +for you. +These are written as `boundary connect ` and are supported for the following connection types: + +- HTTP +- Kubernetes +- PostgreSQL +- RDP +- SSH + +Refer to the [Connect helpers](/boundary/docs/concepts/connection-workflows/connect-helpers) documentation for more information. + ## Built-in vs. exec -We've seen the built-in connect helpers above, however, `boundary connect` +In addition to the built-in connect helpers, `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 `--`: +Refer to the [Exec flag](/boundary/docs/concepts/connection-workflows/exec-flag) documentation for more information. -```shell-session -$ boundary connect ssh -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity -``` +## SSH ProxyCommand -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: +SSH `ProxyCommand` lets you proxy an SSH connection to a target according to a configuration file that you create. +It can help simplify common developer and operator workflows. +You can configure the file to connect to the target ID or the target domain. -- `{{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}}`. +Refer to the [SSH ProxyCommand](/boundary/docs/concepts/connection-workflows/workflow-ssh-proxycommand) documentation for more information. -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: */* -...... -``` - -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 +## Desktop client While using the desktop client, choose the target and connect to retrieve local proxy details. diff --git a/website/content/docs/hcp/get-started/connect-to-target.mdx b/website/content/docs/hcp/get-started/connect-to-target.mdx index dff185fd5..4674ae780 100644 --- a/website/content/docs/hcp/get-started/connect-to-target.mdx +++ b/website/content/docs/hcp/get-started/connect-to-target.mdx @@ -52,198 +52,6 @@ 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 `. - -#### 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_eTcZMueUYv -``` - - - -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_eTcZMueUYv -- -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 provides 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. - - - -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 -``` - - - -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 -``` - - - -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' -``` - - - -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 -``` - - - -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. @@ -265,94 +73,40 @@ Here is an SSH example in dev-mode: $ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope" ``` +## Connect helpers + +Boundary includes connect helpers that automatically accept host SSH key prompts +for you. +These are written as `boundary connect ` and are supported for the following connection types: + +- HTTP +- Kubernetes +- PostgreSQL +- RDP +- SSH + +Refer to the [Connect helpers](/boundary/docs/concepts/connection-workflows/connect-helpers) documentation for more information. + ## Built-in vs. exec -We've seen the built-in connect helpers above, however, `boundary connect` +In addition to the built-in connect helpers, `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 `--`: +Refer to the [Exec flag](/boundary/docs/concepts/connection-workflows/exec-flag) documentation for more information. -```shell-session -$ boundary connect ssh -target-id ttcp_eTcZMueUYv -- -l myuser -i ~/.ssh/identity -``` +## SSH ProxyCommand -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: +SSH `ProxyCommand` lets you proxy an SSH connection to a target according to a configuration file that you create. +It can help simplify common developer and operator workflows. +You can configure the file to connect to the target ID or the target domain. -- `{{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}}`. +Refer to the [SSH ProxyCommand](/boundary/docs/concepts/connection-workflows/workflow-ssh-proxycommand) documentation for more information. -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_eTcZMueUYv - -Target information: - Created Time: Fri, 17 June 2022 18:35:47 PDT - Description: Sample target created by quick setup - ID: ttcp_eTcZMueUYv - Name: CRM Database target - Session Connection Limit: 1 - Session Max Seconds: 28800 - Type: tcp - Updated Time: Fri, 17 June 2022 19:15:17 PDT - Version: 2 - - Scope: - ID: p_A4jfDjZ9jf - Name: Sample project created by quick setup - Parent Scope ID: o_B1xISmpJ5Y - Type: project - - Host Sets: - Host Catalog ID: hcst_YgIU0sHxXp - ID: hsst_pp6f2hfRYB - - 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_eTcZMueUYv \ - -- -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: */* -...... -``` - -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_eTcZMueUYv -``` - -## Connect using the desktop client +## Desktop client While using the desktop client, choose the target and connect to retrieve local proxy details. @@ -378,4 +132,4 @@ Refer to the [Connect to your First Target](/boundary/tutorials/hcp-getting-star Refer to our [basic administration workflows](/boundary/tutorials/hcp-administration) tutorial series -for in depth discussions on managing scopes, targets, identities, and sessions. +for in depth discussions on managing scopes, targets, identities, and sessions. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b773ed881..e7d0a8745 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -165,6 +165,36 @@ } ] }, + { + "title": "Connection workflows", + "routes": [ + { + "title": "Overview", + "path": "concepts/connection-workflows" + }, + { + "title": "Connect helpers", + "path": "concepts/connection-workflows/connect-helpers" + }, + { + "title": "Exec flag", + "path": "concepts/connection-workflows/exec-flag" + }, + { + "title": "SSH ProxyCommand", + "path": "concepts/connection-workflows/workflow-ssh-proxycommand" + }, + { + "title": "Multi-hop sessions", + "badge": { + "text": "HCP/ENT", + "type": "outlined", + "color": "neutral" + }, + "path": "concepts/connection-workflows/multi-hop" + } + ] + }, { "title": "Security", "routes": [ @@ -544,10 +574,6 @@ { "title": "Manage users and groups", "path": "common-workflows/manage-users-groups" - }, - { - "title": "Workflow SSH proxy", - "path": "common-workflows/workflow-ssh-proxycommand" } ] }, diff --git a/website/redirects.js b/website/redirects.js index 8067a019d..82c9a649d 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -138,4 +138,9 @@ module.exports = [ destination: '/boundary/docs/operations/session-recordings', permanent: true, }, + { + source: '/boundary/docs/common-workflows/workflow-ssh-proxycommand', + destination: '/boundary/docs/concepts/connection-workflows/workflow-ssh-proxycommand', + permanent: true, + }, ]