From 334cc9c5c0d361ab0c37305b97dd8b2693d32a7d Mon Sep 17 00:00:00 2001 From: Jeff Malnick Date: Fri, 25 Sep 2020 09:40:34 -0700 Subject: [PATCH] docs: refactor getting started with connect examples (#442) --- .../getting-started/connect-to-target.mdx | 110 ++++++++++++++++++ .../content/docs/getting-started/index.mdx | 34 ++++++ .../docs/getting-started/run-and-login.mdx | 54 ++------- 3 files changed, 154 insertions(+), 44 deletions(-) diff --git a/website/content/docs/getting-started/connect-to-target.mdx b/website/content/docs/getting-started/connect-to-target.mdx index f6152fd01d..667b086179 100644 --- a/website/content/docs/getting-started/connect-to-target.mdx +++ b/website/content/docs/getting-started/connect-to-target.mdx @@ -6,3 +6,113 @@ 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: + +``` +boundary connect ssh -target-id ttcp_1234567890 -- -l +``` + +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. + +## 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 your local Postgres client (`psql`) +- `rdp`: defaults to your local 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. + +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` + +``` +boundary targets update tcp -default-port 53 -id ttcp_1234567890 + +Target information: + Created Time: Fri, 25 Sep 2020 08:43:11 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 09:18:59 PDT + Version: 2 + + Scope: + ID: p_1234567890 + Name: Generated project scope + Parent Scope ID: o_1234567890 + Type: project + + Host Sets: + Host Catalog ID: hcst_1234567890 + ID: hsst_1234567890 + + Attributes: + Default Port: 53 +``` + +We can see in the output above that the default port for our 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: + +``` +boundary hosts update static -address 8.8.8.8 -id hst_1234567890 + +Host information: + Created Time: Fri, 25 Sep 2020 08:43:10 PDT + Description: Provides an initial host in Boundary + Host Catalog ID: hcst_1234567890 + ID: hst_1234567890 + Name: Generated host + Type: static + Updated Time: Fri, 25 Sep 2020 09:28:32 PDT + Version: 2 + + Scope: + ID: p_1234567890 + Name: Generated project scope + Parent Scope ID: o_1234567890 + Type: project + + Attributes: + 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: + +``` +boundary connect -exec dig -target-id ttcp_1234567890 \ + -- @{{boundary.ip}} \ + -p {{boundary.port}} \ + +tcp google.com + +; <<>> DiG 9.10.6 <<>> @127.0.0.1 -p 49757 +tcp google.com +; (1 server found) +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 18306 +;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1 + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 512 +;; QUESTION SECTION: +;google.com. IN A + +;; ANSWER SECTION: +google.com. 299 IN A 216.58.193.78 + +;; Query time: 68 msec +;; SERVER: 127.0.0.1#49757(127.0.0.1) +;; WHEN: Fri Sep 25 09:30:22 PDT 2020 +;; 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. + +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. diff --git a/website/content/docs/getting-started/index.mdx b/website/content/docs/getting-started/index.mdx index c7d0c7c2b5..7199f04dab 100644 --- a/website/content/docs/getting-started/index.mdx +++ b/website/content/docs/getting-started/index.mdx @@ -8,3 +8,37 @@ description: Getting started with Boundary # Getting Started Before getting started with Boundary, it's important to understand a few key concepts. Please consult our [Boundary concepts](/docs/concepts) page to familiarize yourself with Boundary's architecture, and terminology. + +## Requirements + +The examples in Getting Started all revolve around running in `dev mode`. There are a few requirements for running dev mode: + +1. Docker is installed +2. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) is available or a local image cache is available + +## What is Dev Mode? + +Before you can do anything with Boundary, you need to get the Boundary services up and running for the first time. To do this, we're going to run Boundary in `dev` mode. + +Dev mode is an all-in-one installation method for getting started with Boundary quickly. As the name implies, +dev mode is not a production installation method, but instead a way to get Boundary running with a Postgres +database easily. Do not use dev mode in a production environment, see [Poduction Installation](/docs/installing/production) section for +production ready deployment methods. + +Dev mode brings up a fully functioning instance of Boundary, including: + +1. A controller server +2. A worker server +3. A Postgres database + +These components should all be considered ephemeral - no data persistence occurs across dev mode restarts. Along with these external components, dev mode also creates several resources within Boundary to make it easier and faster to connect to your first target: + +1. A organization [scope](/docs/concepts/domain-model/scopes) and a project scope with a default ID of `o_1234567890` and `p_1234567890` respectively. +1. An [auth method](/docs/concepts/domain-model/auth-methods) with a random login name and password with a default auth method ID of `ampw_1234567890`. +1. A static [host catalog](/docs/concepts/domain-model/host-catalogs) with a default ID of `hcst_1234567890`. +1. A static [host](/docs/concepts/domain-model/hosts) and [host set](/docs/concepts/domain-model/host-sets) with default ID's of `hst_1234567890` and `hsst_1234567890` respectively. +1. A TCP [target](/docs/concepts/domain-model/targets) with a default ID of `ttcp_1234567890`. + +All of the default ID suffixes are overridable as well as several other dev mode configurations. To see a complete list of these override flags, consult `boundary dev -h`. + +If you plan on provisioning a large number of resources in dev mode, it's strongly recommended that users leverage our [Terraform Provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary) for managing configuration of Boundary. This will simplify starting up and shutting down your Boundary dev instance. diff --git a/website/content/docs/getting-started/run-and-login.mdx b/website/content/docs/getting-started/run-and-login.mdx index 992585117c..181069d0ee 100644 --- a/website/content/docs/getting-started/run-and-login.mdx +++ b/website/content/docs/getting-started/run-and-login.mdx @@ -8,54 +8,20 @@ description: |- # Run and Login to Boundary -Before you can do anything with Boundary, you need to get the Boundary services up and running for the first time. To do this, we're going to run Boundary in `dev` mode. - -Dev mode is an all-in-one installation method for getting started with Boundary quickly. As the name implies, -dev mode is not a production installation method, but instead a way to get Boundary running with a Postgres -database easily. Do not use dev mode in a production environment, see [Poduction Installation](/docs/installing/production) section for -production ready deployment methods. - -Dev mode brings up a fully functioning instance of Boundary, including: - -1. A controller server -2. A worker server -3. A Postgres database - -These components should all be considered ephemeral - no data persistence occurs across dev mode restarts. It's -strongly recommended that users leverage our [Terraform Provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary) for managing configuration -of Boundary. This will simplify starting up and shutting down your Boundary dev instance. - -## Requiements - -There are a few requirements for running dev mode: - -1. Docker is installed -2. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) is available or a local image cache is available - -## Start Boundary Services - To start Boundary in dev mode: ```bash boundary dev ``` -The above is the most simple way to start the Boundary server in dev mode. However, there are likely some overrides you'll want to configure when -doing so, these include: - -1. Auth method ID -2. Auth method password -3. Account login name - -To use these overrides, set the following flags: +When the Boundary services start, you'll get the randomly generated login name and password in the output. To make things even more simple, you can override these values with hard coded ones instead: ```bash -boundary dev -dev-auth-method-id=ampw_0000000000 -dev-password=foofoofoo -dev-login-name=foo +boundary dev \ + -password=foofoofoo \ + -login-name=foo ``` -Setting these allows you to configure hardcoded auth method ID, password, and login name. You can then use these hardcoded values when configuring clients -such as the Terraform Provider, or when logging into the admin console. - ## Login to Boundary You can use the values from the above example to authenticate. @@ -64,22 +30,22 @@ For CLI users, you can override using flags: ``` # Boundary uses http not https in dev mode -export BOUNDARY_ADDR=http://127.0.0.1:9200 -boundary authenticate password -login-name=foo -password foofoofoo -auth-method-id=ampw_0000000000 +boundary authenticate password --addr='http://127.0.0.1:9200' \ + -login-name=foo \ + -password foofoofoo \ + -auth-method-id=ampw_1234567890 ``` The authenticate to the Admin UI, open [http://127.0.0.1:9200](http://127.0.0.1:9200) in a browser and enter the hard coded login name and password: ![](/img/login-dev-mode.png) -Note: Opening `127.0.0.1:9200` will redirect you to the auth method set in the global scope, which is shown in the image above. - -And of course, you can also use these overrides to configure the [Terraform provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary): +You can also use these overrides to configure the [Terraform provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary): ```hcl provider "boundary" { base_url = "http://127.0.0.1:9200" - auth_method_id = "ampw_0000000000" + auth_method_id = "ampw_1234567890" auth_method_username = "foo" auth_method_password = "foofoofoo" }