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
@@ -1,231 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Deploy and Login
|
||||
description: |-
|
||||
How to deploy HCP Boundary services and login for the first time.
|
||||
---
|
||||
|
||||
# Deploy HCP Boundary and Login
|
||||
|
||||
HCP Boundary provides secure access to remote hosts and infrastructure
|
||||
endpoints. Boundary enables secure connectivity to cloud service catalogs,
|
||||
on-premise infrastructure, and Kubernetes clusters without needing to manage any
|
||||
of the underlying systems or operations.
|
||||
|
||||
## Requirements
|
||||
|
||||
The Getting Started section uses HCP Boundary, a HashiCorp hosted and
|
||||
fully-managed version of the Boundary product.
|
||||
|
||||
To get started with HCP Boundary, users need:
|
||||
|
||||
- A [HashiCorp Cloud Platform](https://portal.cloud.hashicorp.com/sign-up)
|
||||
account
|
||||
- [Installation](/boundary/tutorials/hcp-getting-started/hcp-getting-started-install)
|
||||
of the Boundary CLI
|
||||
- A [Boundary binary](/boundary/downloads) in your `$PATH`
|
||||
- Optionally, an [installation of Boundary
|
||||
Desktop](/boundary/tutorials/hcp-getting-started/hcp-getting-started-desktop-app)
|
||||
|
||||
If you prefer to get started on your local machine, refer to [Run and Login in
|
||||
Dev Mode](/boundary/docs/oss/installing/run-and-login). For more information on Boundary
|
||||
OSS and self-managed installations, refer to [Boundary OSS](/boundary/docs/oss).
|
||||
|
||||
## Deploy an HCP Boundary Cluster
|
||||
|
||||
To deploy an HCP Boundary instance:
|
||||
|
||||
1. Navigate to [HashiCorp Cloud Platform](https://portal.cloud.hashicorp.com/)
|
||||
and login using your credentials.
|
||||
|
||||
1. Click the **Boundary** tab, and then and click **Deploy Boundary** on the
|
||||
right-hand pane.
|
||||
|
||||
1. Fill out the following form details:
|
||||
|
||||
- Instance Name
|
||||
- Administrator Username
|
||||
- Administrator Password
|
||||
|
||||
1. Store the administrator username and password in a safe location. These
|
||||
credentials will be used when authenticating using the Admin Console, CLI, or
|
||||
Terraform.
|
||||
|
||||
1. Click **Deploy** after completing the form. It may take a few minutes to
|
||||
initialize the HCP Boundary instance.
|
||||
|
||||
|
||||
|
||||
## Login to HCP Boundary
|
||||
|
||||
Once the deployment is complete, the HCP Boundary instance can be accessed
|
||||
directly from the HCP Boundary portal using the credentials created during
|
||||
setup.
|
||||
|
||||
1. From the HCP Boundary portal page, click the **Open Admin UI** button.
|
||||
|
||||
1. Enter the admin username and password you created when you deployed the new
|
||||
instance, and click **Authenticate**.
|
||||
|
||||
1. The **Welcome to Boundary** setup wizard will launch automatically.
|
||||
|
||||
There are two options for Boundary’s initial setup:
|
||||
|
||||
- Quick setup
|
||||
- Manual
|
||||
|
||||
|
||||
|
||||
The **Quick setup** is recommended for new users, and generates a set of initial
|
||||
resources to assist in connecting to your first target.
|
||||
|
||||
|
||||
|
||||
The **Manual** setup drops the user directly into Boundary, without any
|
||||
provisioned resources.
|
||||
|
||||
Upon completion of the setup wizard, you will be logged into your HCP Boundary
|
||||
instance's Global scope via the web UI. This is the default scope for all new
|
||||
Boundary clusters.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI">
|
||||
|
||||
1. In the HCP Boundary portal, open the **Boundary Overview** page, and click
|
||||
the **copy icon** in the **Copy this into Boundary Desktop** section. This
|
||||
copies your environment’s Boundary **Cluster URL**.
|
||||
|
||||
1. Open a terminal session and set the `BOUNDARY_ADDR` environment variable to
|
||||
the copied Cluster URL.
|
||||
|
||||
```shell-session
|
||||
$ export BOUNDARY_ADDR=<boundary-cluster-url>
|
||||
```
|
||||
|
||||
1. Log in with the administrator credentials you created when you deployed the
|
||||
HCP Boundary instance.
|
||||
|
||||
```shell-session
|
||||
$ boundary authenticate
|
||||
Please enter the login name (it will be hidden):
|
||||
Please enter the password (it will be hidden):
|
||||
|
||||
Authentication information:
|
||||
Account ID: acctpw_VOeNSFX8pQ
|
||||
Auth Method ID: ampw_wxzojlKJLN
|
||||
Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
|
||||
User ID: u_1vUkf5fPs9
|
||||
|
||||
The token was successfully stored in the chosen keyring and is not displayed here.
|
||||
```
|
||||
|
||||
You are now logged into your HCP Boundary instance's Global scope via the CLI.
|
||||
This is the default scope for all new Boundary clusters.
|
||||
|
||||
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="Desktop Client">
|
||||
|
||||
|
||||
[Boundary Desktop](/boundary/downloads) can be used to
|
||||
connect to HCP Boundary.
|
||||
|
||||
To get started with Boundary Desktop:
|
||||
|
||||
1. Install Boundary Desktop.
|
||||
1. Enter your HCP Boundary instance’s Cluster URL.
|
||||
1. Enter the login name and password.
|
||||
|
||||
To authenticate using the Boundary desktop client, launch Boundary desktop
|
||||
client and connect to boundary to using your environment's **Cluster URL**.
|
||||
|
||||
You can find your environment’s Cluster URL In the HCP portal. Open the
|
||||
**Boundary Overview** page and click the **copy icon** in the **Copy this into
|
||||
Boundary Desktop** section. This copies your environment’s Boundary **Cluster
|
||||
URL**.
|
||||
|
||||
The admin username and password from instance creation can be used for initial
|
||||
setup. Once additional users have been created, they can also log in to HCP
|
||||
Boundary using the Boundary Desktop app.
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Terraform">
|
||||
|
||||
|
||||
You can also use these overrides to configure the [Terraform provider for
|
||||
Boundary](https://registry.terraform.io/providers/hashicorp/boundary):
|
||||
|
||||
```hcl
|
||||
provider "boundary" {
|
||||
base_url = "hcp-boundary-cluster-url"
|
||||
auth_method_id = "auth-method-id"
|
||||
auth_method_username = "admin-username"
|
||||
auth_method_password = "admin-password"
|
||||
}
|
||||
```
|
||||
|
||||
To find your environment’s `base_url`:
|
||||
|
||||
1. In the HCP portal, open the **Boundary Overview** page.
|
||||
1. Click the **copy icon** in the **Copy this into Boundary Desktop** section.
|
||||
This copies your environment’s Boundary **Cluster URL**.
|
||||
|
||||
To find your environment’s default `auth_method_id`:
|
||||
|
||||
1. In your HCP Boundary portal, click the Admin UI button.
|
||||
1. Log in to the Admin Console by entering the admin username and password you
|
||||
created when you deployed the HCP Boundary instance, and click **Authenticate**.
|
||||
1. Click **Auth Methods**.
|
||||
1. Click the **copy icon** for the Password **Auth Method ID**
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Tutorial
|
||||
|
||||
- Refer to the [Create a Boundary Instance on
|
||||
HCP](/boundary/tutorials/hcp-getting-started/hcp-getting-started-create)
|
||||
tutorial to learn how to deploy a Boundary instance.
|
||||
- Refer to the [Install Boundary
|
||||
Desktop](/boundary/tutorials/hcp-getting-started/hcp-getting-started-desktop-app)
|
||||
tutorial to learn how to use the Boundary desktop to connect to a running HCP
|
||||
Boundary instance.
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
||||
See [connecting to your first target](/boundary/docs/getting-started/connect-to-target)
|
||||
for how to use HCP Boundary to run your first SSH session.
|
||||
+50
-60
@@ -1,51 +1,48 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Connect to Target
|
||||
page_title: Connect to your first target
|
||||
description: |-
|
||||
Connecting to your first target
|
||||
---
|
||||
|
||||
# Connect to Your First Target
|
||||
# Connect to your first target
|
||||
|
||||
The [Quick setup
|
||||
wizard](/boundary/docs/getting-started/deploy-and-login#login-to-hcp-boundary)
|
||||
is the fastest way to onboard a target to HCP Boundary.
|
||||
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
|
||||
```
|
||||
|
||||
The Quick setup wizard creates a default `tcp` target with the port `22` (the default SSH port using TCP).
|
||||
The target is created with the address `127.0.0.1`.
|
||||
When you execute `boundary connect` against this target, Boundary establishes a local, authenticated proxy to the address on the target's default port (`127.0.0.1:22`.)
|
||||
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
|
||||
```
|
||||
|
||||
## Connect using the CLI
|
||||
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.
|
||||
|
||||
To connect to the initial EC2 Instances target:
|
||||
For the rest of this guide, assume the default is used.
|
||||
|
||||
1. Copy the **EC2 Instances** target ID (such as `ttcp_ZnHEU9h8qX`).
|
||||
|
||||
1. Open a terminal session. Export the Boundary **Cluster URL** as an environment
|
||||
variable.
|
||||
|
||||
```shell-session
|
||||
$ export BOUNDARY_ADDR=<boundary-cluster-url>
|
||||
```
|
||||
|
||||
1. Connect to the target.
|
||||
|
||||
```shell-session
|
||||
$ boundary connect -target-id ttcp_eTcZMueUYv
|
||||
```
|
||||
|
||||
The output displays the address and port that your SSH client must use.
|
||||
In the next section the `ssh` connect helper is used 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.
|
||||
|
||||
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
|
||||
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
|
||||
@@ -63,7 +60,7 @@ 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
|
||||
$ boundary connect ssh -target-id ttcp_1234567890
|
||||
```
|
||||
|
||||
If you want to pass additional flags to the SSH client, add them to the command
|
||||
@@ -71,7 +68,7 @@ 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_eTcZMueUYv -- -l some-other-user
|
||||
$ 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
|
||||
@@ -79,7 +76,7 @@ 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
|
||||
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
|
||||
@@ -95,12 +92,12 @@ single explicit value, however other flags are supported:
|
||||
- `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 reused
|
||||
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:
|
||||
Here is an SSH example in dev mode:
|
||||
|
||||
```shell-session
|
||||
$ boundary connect ssh -target-name "Generated target" -target-scope-name "Generated project scope"
|
||||
@@ -127,7 +124,7 @@ 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_eTcZMueUYv -- -l myuser -i ~/.ssh/identity
|
||||
$ 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
|
||||
@@ -146,29 +143,26 @@ 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
|
||||
$ boundary targets update tcp -default-port 443 -id ttcp_1234567890
|
||||
|
||||
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
|
||||
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, 17 June 2022 19:15:17 PDT
|
||||
Updated Time: Fri, 25 Sep 2020 18:36:18 PDT
|
||||
Version: 2
|
||||
|
||||
Scope:
|
||||
ID: p_A4jfDjZ9jf
|
||||
Name: Sample project created by quick setup
|
||||
Parent Scope ID: o_B1xISmpJ5Y
|
||||
ID: p_1234567890
|
||||
Name: Generated project scope
|
||||
Parent Scope ID: o_1234567890
|
||||
Type: project
|
||||
|
||||
Host Sets:
|
||||
Host Catalog ID: hcst_YgIU0sHxXp
|
||||
ID: hsst_pp6f2hfRYB
|
||||
|
||||
Attributes:
|
||||
Default Port: 443
|
||||
```
|
||||
@@ -179,7 +173,7 @@ 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 \
|
||||
$ boundary connect -exec curl -target-id ttcp_1234567890 \
|
||||
-- -vvsL --output /dev/null hashicorp.com
|
||||
|
||||
* Trying 76.76.21.21...
|
||||
@@ -198,7 +192,7 @@ 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
|
||||
$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890
|
||||
```
|
||||
|
||||
## Connect using Desktop Client
|
||||
@@ -211,7 +205,7 @@ proxy details.
|
||||
playsInline
|
||||
autoPlay
|
||||
loop
|
||||
className="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
>
|
||||
<source
|
||||
type="video/mp4"
|
||||
@@ -219,12 +213,8 @@ proxy details.
|
||||
/>
|
||||
</video>
|
||||
|
||||
## Tutorial
|
||||
|
||||
Refer to the [Connect to your First Target](/boundary/tutorials/hcp-getting-started/hcp-getting-started-connect) tutorial for steps on how to create a host catalog, host set, and a target in Boundary.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Refer to our [basic administration
|
||||
workflows](/boundary/tutorials/hcp-administration) tutorial series
|
||||
for in depth discussions on managing scopes, targets, identities, and sessions.
|
||||
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.
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Installing Boundary
|
||||
description: |-
|
||||
How to install boundary.
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
This section covers installing Boundary for development and production modes of operation.
|
||||
@@ -1,231 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Production Installation
|
||||
description: |-
|
||||
How to install Boundary in a production environment
|
||||
---
|
||||
|
||||
# Production Installation
|
||||
|
||||
Installing Boundary in a production setting requires prerequisits for infrastructure. At the most basic level, Boundary operators should run a minimum of 3 controllers and 3 workers. Running 3 of each server type gives a fundamental level of high availability for the control plane (controller), as well as bandwidth for number of sessions on the data plane (worker). Both server type should be ran in a fault tolerant setting, that is, in a self-healing environment such as an auto-scaling group. The documentation here does not cover self-healing infrastructure and assumes the operator has their preferred scheduling methods for these environments.
|
||||
|
||||
## Network Requirements
|
||||
|
||||
- Client -> Controller port is :9200
|
||||
- Worker -> Controller port is :9201
|
||||
- Client -> Worker port is :9202
|
||||
- Workers must have a route and port access to the targets which they service
|
||||
|
||||
## Architecture
|
||||
|
||||
The general architecture for the server infrastructure requires 3 controllers and 3 workers. The documentation here uses virtual machines running on Amazon EC2 as the example environment, but this use
|
||||
case can be extrapolated to almost any cloud platform to suit operator needs:
|
||||
|
||||
|
||||
|
||||
As shown above, Boundary is broken up into its controller and worker server components across 3 [EC2 instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), in
|
||||
3 separate [subnets](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/subnet), in three separate availability zones, with the controller API and UI being publically exposed by an [application load balancer (ALB)](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb). The worker and controller VM's are in independent [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity.
|
||||
|
||||
Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS](https://aws.amazon.com/kms/). In the example above, we're using AWS managed services for these components. For Postgres, we're using [RDS](https://aws.amazon.com/rds/) and for KMS we're using Amazon's [Key Management Service](https://aws.amazon.com/kms/).
|
||||
|
||||
## Architecture Breakdown
|
||||
|
||||
### API and Console Load Balancer
|
||||
|
||||
Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary server's in private networks and using load balancing tecniques to expose services such as the API and administrative console to public networks. In the production architecture, we recommend load balancing using a layer 7 load balancer and further constraining ingress to that load balancer with layer 4 constraints such as [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) or [IP tables](https://wiki.archlinux.org/index.php/Iptables).
|
||||
|
||||
For general configuration, we recommend the following:
|
||||
|
||||
- HTTPS listener with valid TLS certificate for the domain it's serving or TLS passthrough
|
||||
- Health check port should use :9200 with TCP protocol
|
||||
|
||||
### Controller Configuration
|
||||
|
||||
When running Boundary controller as a service we recommend storing the file at `/etc/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it.
|
||||
|
||||
Example controller configuration:
|
||||
|
||||
```hcl
|
||||
# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
|
||||
disable_mlock = true
|
||||
|
||||
# Controller configuration block
|
||||
controller {
|
||||
# This name attr must be unique!
|
||||
name = "demo-controller-${count.index}"
|
||||
# Description of this controller
|
||||
description = "A controller for a demo!"
|
||||
}
|
||||
|
||||
# API listener configuration block
|
||||
listener "tcp" {
|
||||
# Should be the address of the NIC that the controller server will be reached on
|
||||
address = "${self.private_ip}:9200"
|
||||
# The purpose of this listener block
|
||||
purpose = "api"
|
||||
# Should be enabled for production installs
|
||||
tls_disable = true
|
||||
# Enable CORS for the Admin UI
|
||||
cors_enabled = true
|
||||
cors_allowed_origins = ["*"]
|
||||
}
|
||||
|
||||
# Data-plane listener configuration block (used for worker coordination)
|
||||
listener "tcp" {
|
||||
# Should be the IP of the NIC that the worker will connect on
|
||||
address = "${self.private_ip}:9201"
|
||||
# The purpose of this listener
|
||||
purpose = "cluster"
|
||||
# Should be enabled for production installs
|
||||
tls_disable = true
|
||||
}
|
||||
|
||||
# Root KMS configuration block: this is the root key for Boundary
|
||||
# Use a production KMS such as AWS KMS in production installs
|
||||
kms "aead" {
|
||||
purpose = "root"
|
||||
aead_type = "aes-gcm"
|
||||
key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
|
||||
key_id = "global_root"
|
||||
}
|
||||
|
||||
# Worker authorization KMS
|
||||
# Use a production KMS such as AWS KMS for production installs
|
||||
# This key is the same key used in the worker configuration
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
|
||||
# Recovery KMS block: configures the recovery key for Boundary
|
||||
# Use a production KMS such as AWS KMS for production installs
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_recovery"
|
||||
}
|
||||
|
||||
# Database URL for postgres. This can be a direct "postgres://"
|
||||
# URL, or it can be "file://" to read the contents of a file to
|
||||
# supply the url, or "env://" to name an environment variable
|
||||
# that contains the URL.
|
||||
database {
|
||||
url = "postgresql://boundary:boundarydemo@${aws_db_instance.boundary.endpoint}/boundary"
|
||||
}
|
||||
```
|
||||
|
||||
### Worker Configuration
|
||||
|
||||
```hcl
|
||||
listener "tcp" {
|
||||
purpose = "proxy"
|
||||
tls_disable = true
|
||||
}
|
||||
|
||||
worker {
|
||||
# Name attr must be unique
|
||||
name = "demo-worker-${count.index}"
|
||||
description = "A default worker created demonstration"
|
||||
initial_upstreams = [
|
||||
"${aws_instance.controller[0].private_ip}",
|
||||
"${aws_instance.controller[1].private_ip}",
|
||||
"${aws_instance.controller[2].private_ip}"
|
||||
]
|
||||
}
|
||||
|
||||
# must be same key as used on controller config
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
```
|
||||
|
||||
name must be unique!
|
||||
|
||||
### Installation
|
||||
|
||||
`TYPE` below can be either `worker` or `controller`.
|
||||
|
||||
1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service
|
||||
See above example configurations.
|
||||
|
||||
2. `/usr/local/bin/boundary`: The Boundary binary
|
||||
Can build from https://github.com/hashicorp/boundary or download binary from our release pages.
|
||||
|
||||
3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service
|
||||
Example:
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=${NAME} ${TYPE}
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl
|
||||
User=boundary
|
||||
Group=boundary
|
||||
LimitMEMLOCK=infinity
|
||||
Capabilities=CAP_IPC_LOCK+ep
|
||||
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Here's a simple install script that creates the boundary group and user, installs the
|
||||
systemd unit file and enables it at startup:
|
||||
|
||||
```
|
||||
#!/bin/bash
|
||||
# Installs the boundary as a service for systemd on linux
|
||||
# Usage: ./install.sh <worker|controller>
|
||||
|
||||
TYPE=$1
|
||||
NAME=boundary
|
||||
|
||||
sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service
|
||||
[Unit]
|
||||
Description=${NAME} ${TYPE}
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl
|
||||
User=boundary
|
||||
Group=boundary
|
||||
LimitMEMLOCK=infinity
|
||||
Capabilities=CAP_IPC_LOCK+ep
|
||||
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Add the boundary system user and group to ensure we have a no-login
|
||||
# user capable of owning and running Boundary
|
||||
sudo adduser --system --group boundary || true
|
||||
sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl
|
||||
sudo chown boundary:boundary /usr/local/bin/boundary
|
||||
|
||||
# Make sure to initialize the DB before starting the service. This will result in
|
||||
# a database already initialized warning if another controller or worker has done this
|
||||
# already, making it a lazy, best effort initialization
|
||||
if [ "${TYPE}" = "controller" ]; then
|
||||
sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true
|
||||
fi
|
||||
|
||||
sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable ${NAME}-${TYPE}
|
||||
sudo systemctl start ${NAME}-${TYPE}
|
||||
```
|
||||
|
||||
### Postgres Configuration
|
||||
|
||||
TBD
|
||||
|
||||
### KMS Configuration
|
||||
|
||||
TBD
|
||||
Reference in new issue
Block a user