docs: Restructure table of contents (#3230)
* docs: Restructure table of contents * docs: Copy edits to Develop/Get started sections * docs: Add index to HCP Boundary section * docs: Move OSS/Install section to top-level * docs: Move Concepts above Configuration
This commit is contained in:
Dan Heath authored and 
GitHub committed
1 parent
dba7d88523
commit
d49b7ae629
22 files changed
+361
-486
No files matched your search
@@ -0,0 +1,220 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Connect to your first target
|
||||
description: |-
|
||||
Connecting to your first target
|
||||
---
|
||||
|
||||
# Connect to your first target
|
||||
|
||||
The default target is a `tcp` target with a default port of `22` (which
|
||||
corresponds to the default SSH port using TCP). This target is set up with
|
||||
`127.0.0.1` as its address. When you execute `boundary connect` against this
|
||||
target, a local authenticated proxy to the address is established on the
|
||||
target's default port (`127.0.0.1:22`).
|
||||
|
||||
```shell-session
|
||||
$ boundary connect -target-id ttcp_1234567890
|
||||
```
|
||||
|
||||
There is also a secondary `tcp` target with (`ttcp_0987654321`) which uses host
|
||||
sets instead of an address. The host sets for this target contain the default
|
||||
host, which has the address 127.0.0.1. When you execute `boundary connect`
|
||||
against this target, the single available host will be selected and a local
|
||||
authenticated proxy to the host is also established on the target's default port
|
||||
(127.0.0.1:22).
|
||||
|
||||
```shell-session
|
||||
boundary connect -target-id ttcp_0987654321
|
||||
```
|
||||
|
||||
For the purpose of this guide, both of these targets accomplish the same goal,
|
||||
however they have different purposes. Refer to the
|
||||
[domain](/boundary/docs/concepts/domain-model/index) documentation for more information.
|
||||
|
||||
For the rest of this guide, assume the default is used.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
`Ctrl-C/Command-C` the `boundary connect` process to shut down the session.
|
||||
|
||||
### Using Connect Helpers
|
||||
|
||||
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,
|
||||
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 will be 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.
|
||||
|
||||
## Selecting Targets
|
||||
|
||||
When using `boundary connect` you must identify the target used for connecting.
|
||||
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
|
||||
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:
|
||||
|
||||
```shell-session
|
||||
$ 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,
|
||||
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
|
||||
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 `--`:
|
||||
|
||||
```shell-session
|
||||
$ boundary connect ssh -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
- `{{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}}`.
|
||||
|
||||
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: */*
|
||||
...<truncated output>...
|
||||
```
|
||||
|
||||
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 Desktop Client
|
||||
|
||||
While using the desktop client, choose the target and connect to retrieve local
|
||||
proxy details.
|
||||
|
||||
<video
|
||||
muted
|
||||
playsInline
|
||||
autoPlay
|
||||
loop
|
||||
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
>
|
||||
<source
|
||||
type="video/mp4"
|
||||
src="https://www.datocms-assets.com/2885/1613612836-boundary-desktop-clickthrough-connect-target-v1-0-0.mp4"
|
||||
/>
|
||||
</video>
|
||||
|
||||
## Next Steps
|
||||
|
||||
See our [basic administration
|
||||
workflows](/boundary/tutorials/oss-administration)
|
||||
for in depth discussion on managing scopes, targets, identities, and sessions.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: What is Dev Mode?
|
||||
description: Getting started with Boundary OSS in Dev mode
|
||||
---
|
||||
|
||||
# What is Dev Mode?
|
||||
|
||||
Dev mode is a method for getting started with Boundary quickly for testing and
|
||||
learning purposes. As the name implies, dev mode is not a production
|
||||
installation method, and provides a way to get Boundary running with a Postgres
|
||||
database easily. Do not use dev mode in a production environment, see the
|
||||
[Production Installation](/boundary/docs/oss/installing/high-availability) section for
|
||||
production-ready deployment methods.
|
||||
|
||||
Dev mode brings up a fully-functioning instance of Boundary, including:
|
||||
|
||||
- A controller server
|
||||
- A worker server
|
||||
- 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. An org [scope](/boundary/docs/concepts/domain-model/scopes) and a project scope with a
|
||||
default ID of `o_1234567890` and `p_1234567890` respectively.
|
||||
1. A password [auth method](/boundary/docs/concepts/domain-model/auth-methods) with a
|
||||
default auth method ID of `ampw_1234567890`.
|
||||
1. An OIDC [auth method](/boundary/docs/concepts/domain-model/auth-methods) with a
|
||||
default auth method ID of `amoidc_1234567890`.
|
||||
1. An admin user with login name `admin` and password `password`.
|
||||
1. An unprivileged user with login name `user` and password `password`.
|
||||
1. A static [host catalog](/boundary/docs/concepts/domain-model/host-catalogs) with a
|
||||
default ID of `hcst_1234567890`.
|
||||
1. A static [host](/boundary/docs/concepts/domain-model/hosts) and [host
|
||||
set](/boundary/docs/concepts/domain-model/host-sets) with default ID's of
|
||||
`hst_1234567890` and `hsst_1234567890` respectively.
|
||||
1. A TCP [target](/boundary/docs/concepts/domain-model/targets) with a default ID of
|
||||
`ttcp_1234567890`, directly set-up with an address and port.
|
||||
1. A TCP [target](/boundary/docs/concepts/domain-model/targets) with a default ID of
|
||||
`ttcp_0987654321` using the previously mentioned static host set.
|
||||
|
||||
The default ID suffixes can be overwritten or randomly generated, and there are
|
||||
many other dev mode controls. 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.
|
||||
|
||||
## Requirements
|
||||
|
||||
There are a few requirements for running dev mode:
|
||||
|
||||
- [Docker](https://docs.docker.com/get-docker/) is installed
|
||||
- A route to download the [Postgres Docker
|
||||
image](https://hub.docker.com/_/postgres) is available or a local image cache
|
||||
is available
|
||||
- A [Boundary binary](/boundary/downloads) in your `$PATH`
|
||||
- _Optionally_, an [installation of Boundary
|
||||
Desktop](/boundary/tutorials/oss-getting-started/oss-getting-started-desktop-app)
|
||||
if you want to use the desktop examples
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Run and log in to Boundary
|
||||
description: |-
|
||||
How to run Boundary services in dev mode and login for the first time.
|
||||
---
|
||||
|
||||
# Run and log in to Boundary
|
||||
|
||||
To start Boundary in dev mode:
|
||||
|
||||
```shell-session
|
||||
$ boundary dev
|
||||
```
|
||||
|
||||
## Log in to Boundary
|
||||
|
||||
Boundary uses a predictable login name (`admin`) and password (`password`) in
|
||||
dev mode. These can be overridden, or randomly generated, with flags to
|
||||
`boundary dev`. The auth method resource in the global scope is set as the primary auth method for that scope. This allows you to omit the auth method ID when authenticating, enabling the short-form `boundary authenticate`:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
|
||||
```shell-session
|
||||
$ boundary authenticate
|
||||
Please enter the login name (it will be hidden):
|
||||
Please enter the password (it will be hidden):
|
||||
```
|
||||
|
||||
If you are on Windows or macOS, the system password store will be used to store
|
||||
the new token. On any other operating system, you may get an error indicating
|
||||
that the token could not be stored. Boundary defaults to using
|
||||
[pass](https://www.passwordstore.org/) on these machines, which uses [GNU
|
||||
Privacy Guard](https://gnupg.org/) to encrypt values. If it is not available,
|
||||
the token will be displayed and can be stored in a system of your choice and
|
||||
passed in via the `BOUNDARY_TOKEN` environment variable.
|
||||
|
||||
It is recommended to make use of `pass` or another alternative (such as any
|
||||
implementation of the freedesktop.org Secret Service feature). Installation and
|
||||
configuration of `pass` or other alternatives is beyond the scope of this
|
||||
article; consult the documentation for `pass` or your specific OS distribution
|
||||
help pages.
|
||||
|
||||
Note that if `-format json` is used on this command, Boundary will not save the
|
||||
token to the system password store. In this case, the authentication information
|
||||
will only be printed to your terminal in JSON format. You can use the
|
||||
`BOUNDARY_TOKEN` environment variable or `-token` flag to provide the token in
|
||||
subsequent commands.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Admin Console">
|
||||
|
||||
|
||||
To authenticate to the Admin UI, open
|
||||
[http://127.0.0.1:9200](http://127.0.0.1:9200) in a browser and enter the login
|
||||
name and password:
|
||||
|
||||
<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
|
||||
<source
|
||||
type="video/mp4"
|
||||
src="https://www.datocms-assets.com/2885/1602260993-boundary-clickthrough-getting-started-run-and-login.mp4"
|
||||
/>
|
||||
</video>
|
||||
|
||||
</Tab>
|
||||
|
||||
|
||||
<Tab heading="Desktop Client">
|
||||
<p>
|
||||
|
||||
|
||||
To authenticate using the Boundary desktop client, launch Boundary desktop client
|
||||
and connect to boundary to using [http://127.0.0.1:9200](http://127.0.0.1:9200)
|
||||
and enter the login name and password:
|
||||
|
||||
<video
|
||||
muted
|
||||
playsInline
|
||||
autoPlay
|
||||
loop
|
||||
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
>
|
||||
<source
|
||||
type="video/mp4"
|
||||
src="https://www.datocms-assets.com/2885/1613612831-boundary-desktop-clickthrough-authenticate-v1-0-0.mp4"
|
||||
/>
|
||||
</video>
|
||||
|
||||
</p>
|
||||
</Tab>
|
||||
|
||||
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
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_1234567890"
|
||||
auth_method_username = "admin"
|
||||
auth_method_password = "password"
|
||||
}
|
||||
```
|
||||
|
||||
Note in the example above we're setting `base_url` to `http` and not `https` as
|
||||
the Boundary server does not use TLS in development mode.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
||||
See [connecting to your first
|
||||
target](/boundary/docs/oss/installing/connect-to-dev-target) for how to use Boundary to
|
||||
run your first SSH session.
|
||||
Reference in new issue
Block a user