Hashiconf docs changes (#2178)
Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com> Co-authored-by: XingLu Wang <95828202+xingluw@users.noreply.github.com> Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> Co-authored-by: Jeff Mitchell <jeffrey.mitchell@gmail.com> Co-authored-by: irenarindos <irena.rindos@gmail.com> Co-authored-by: Irena Rindos <irenarindos@users.noreply.github.com> Co-authored-by: Louis Ruch <louisruch@gmail.com> Co-authored-by: XingLu Wang <xinglu.wang@hashicorp.com> Co-authored-by: XingLu Wang <95828202+xingluw@users.noreply.github.com>
This commit is contained in:
43 files changed
+1364
-479
No files matched your search
@@ -41,7 +41,7 @@ $ boundary authenticate password -login-name=admin -password password -auth-meth
|
||||
|
||||
## SSH to Target
|
||||
|
||||
Running Boundary in [dev mode](https://www.boundaryproject.io/docs/getting-started#what-is-dev-mode) creates other
|
||||
Running Boundary in [dev mode](/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`.
|
||||
|
||||
@@ -122,7 +122,7 @@ $ boundary authenticate password -login-name=admin -password password -auth-meth
|
||||
|
||||
## Authorize the Session
|
||||
|
||||
Running Boundary in [dev mode](https://www.boundaryproject.io/docs/getting-started#what-is-dev-mode) creates other
|
||||
Running Boundary in [dev mode](/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`.
|
||||
|
||||
|
||||
@@ -58,6 +58,10 @@ A Vault credential store has the following additional attributes:
|
||||
- `namespace` - (optional)
|
||||
A Vault [namespace][]. Requires Vault Enterprise.
|
||||
|
||||
### Static Credential Store Attributes
|
||||
|
||||
A Static credential store has no additional attributes and only supports the optional attributes.
|
||||
|
||||
## Referenced By
|
||||
|
||||
- [Credential Library][]
|
||||
@@ -164,3 +168,7 @@ $ vault policy write boundary-controller boundary-controller-policy.hcl
|
||||
[renewable]: https://www.vaultproject.io/api-docs/auth/token#renewable-1
|
||||
[periodic]: https://www.vaultproject.io/api-docs/auth/token#token_period
|
||||
[orphan]: https://www.vaultproject.io/api-docs/auth/token#orphan
|
||||
|
||||
### Static Credential Store
|
||||
|
||||
A Static credential store allows for a user-supplied credentials managed by Boundary. Credentials are encrypted and stored directly in Boundary. Currently, the static credential store can hold credentials of type `username_password`.
|
||||
@@ -13,6 +13,16 @@ on a [host][] for a [session][].
|
||||
|
||||
## Attributes
|
||||
|
||||
## Credential types
|
||||
|
||||
Optionally, credentials can be typed to indicate compliance with a specific
|
||||
format. For example, Boundary allows for `username_password` credentials that
|
||||
contain the following fields:
|
||||
|
||||
- `username` - The username field assocaited with the credential.
|
||||
|
||||
- `password` - The password field assocaited with the credential.
|
||||
|
||||
## Referenced By
|
||||
|
||||
- [Credential Store][]
|
||||
|
||||
@@ -49,14 +49,20 @@ supported for the specific inputs and examples with those inputs.
|
||||
|
||||
# Next Steps
|
||||
|
||||
Be sure Boundary is able to run locally with the instructions at [Getting
|
||||
Started](/docs/getting-started). Then, learn how to create targets and initiate
|
||||
a session with [Connect to Your First
|
||||
Target](/docs/getting-started/connect-to-target).
|
||||
There are several options for deploying Boundary:
|
||||
|
||||
# Further Reading
|
||||
1. HCP Boundary as a fully-managed service
|
||||
2. Boundary OSS for self-managed deployments
|
||||
3. Dev mode for testing and learning purposes
|
||||
|
||||
For more information see our general recommendations for [deployment
|
||||
architecture](/docs/installing/high-availability), and see the [security
|
||||
model](/docs/concepts/security) documentation for an explanation of the security
|
||||
foundations of Boundary.
|
||||
Boundary can be deployed easily as a managed service using the HashiCorp Cloud
|
||||
Platform. Refer to the [Getting Started](/docs/getting-started) section to learn
|
||||
more about HCP Boundary.
|
||||
|
||||
To learn more about Boundary OSS and self-managed deployments, refer to the
|
||||
[Boundary OSS](/docs/oss) docs.
|
||||
|
||||
Boundary can be run locally in [Dev mode](/docs/oss/installing/dev-mode). Refer
|
||||
to the [Connect to Your First
|
||||
Target](/docs/oss/installing/connect-to-dev-target) section to learn about
|
||||
creating targets and initiating a sessions in dev mode.
|
||||
@@ -29,45 +29,6 @@ provides broad compatibility with a wide array of clients.
|
||||
It is possible to require client certificates; see the configuration for
|
||||
`listener` blocks to see the available TLS parameters.
|
||||
|
||||
## Worker-to-Controller TLS
|
||||
|
||||
The service exposed by the Controller to handle Worker requests takes
|
||||
advantage of the [KMS](/docs/concepts/security/data-encryption) key designated
|
||||
for `worker-auth` within Boundary's configuration file, which must point to the
|
||||
same key on the KMS for both the Controller and the Worker. Security of the
|
||||
connection relies on secure transmission of a single set of allowed TLS
|
||||
parameters, which forms the entire allowable CA chain for the connection.
|
||||
|
||||
TLS establishment is performed as follows:
|
||||
|
||||
1. The Worker generates a TLS certificate acting as a self-contained chain, as
|
||||
well as a nonce. The generated key type is currently Ed25519. The certificate is
|
||||
valid for a total of 2.5 minutes: thirty seconds before the current time (to
|
||||
allow for some minor clock drift) and two minutes after (to allow time to
|
||||
establish the connection).
|
||||
|
||||
2. The Worker marshals the TLS chain and nonce and encrypts the resulting bytes
|
||||
via the shared KMS. This value is marshaled and split into chunks.
|
||||
|
||||
3. The Worker establishes a TLS 1.3 connection to the Controller. The encrypted
|
||||
value is transmitted to the Controller via the TLS ALPN field as numbered
|
||||
chunks.
|
||||
|
||||
4. The Controller reads the chunks and reassembles them into the original
|
||||
encrypted value.
|
||||
|
||||
5. The Controller decrypts this value via the shared KMS. If successful, the
|
||||
Controller validates that the nonce is not known to ensure that this is not a
|
||||
replay. The nonce value is checked against and stored into the database,
|
||||
ensuring that nonce replay cannot occur across controllers.
|
||||
|
||||
6. The Controller uses the decrypted parameters to configures its TLS stack with
|
||||
the same certificate and key.
|
||||
|
||||
7. The connection is mutually authenticated; on each end, only the single
|
||||
self-signed CA certificate that was securely transmitted is configured as a
|
||||
valid root CA for validation checking.
|
||||
|
||||
## Client-to-Worker TLS
|
||||
|
||||
Workers do not require any configuration for their client-facing listeners to
|
||||
@@ -131,3 +92,188 @@ In the future, to support other client paradigms, we may support user
|
||||
configuration of the Worker's client-facing TLS. In this model, the shared
|
||||
certificate/private key would instead act as credentials for the session,
|
||||
similar to a username/password.
|
||||
|
||||
|
||||
## Worker-to-Upstream TLS
|
||||
|
||||
Workers connect to upstreams (Controllers, or other Workers) via TLS
|
||||
connections. In order to make these connections, Workers have to be
|
||||
authenticated to the cluster. How this authentication and session establishment
|
||||
takes place can happen in one of two ways: by a built-in X.509-based PKI system,
|
||||
or by leveraging a KMS system to provide secure transport of authentication
|
||||
information.
|
||||
|
||||
The KMS-based mechanism provides zero-touch registration of Workers to a
|
||||
cluster, while the PKI mechanism provides positive access control at
|
||||
registration time. Currently, HCP Boundary deployments only support PKI
|
||||
authentication for self-managed Workers.
|
||||
|
||||
### PKI-Based Worker Authentication
|
||||
|
||||
In the PKI-based authentication mechanisms, Workers are registered to the
|
||||
cluster by informing the cluster of a Worker's public signing and encryption
|
||||
keys. The cluster then returns to the Worker a set of signed certificates and a
|
||||
Controller public encryption key. This process is arbited by the operator (or a
|
||||
provisioning system) to provide security for transport of the initial public key
|
||||
material.
|
||||
|
||||
The PKI mechanism is set up via transport of a single value from the Worker to
|
||||
any cluster Controller. Once established, certificates and encryption keys are
|
||||
automatically rotated periodically, currently at a period of two weeks.
|
||||
|
||||
There may be various permutations of this mechanism in the future; there is only
|
||||
one mechanism now, referred to as _worker-led_ registration because the Worker
|
||||
produces the initial key material.
|
||||
|
||||
Note that the mechanisms described in this section omit detail for clarity.
|
||||
|
||||
#### Worker-Led PKI-Based Registration
|
||||
|
||||
Registration proceeds as follows:
|
||||
|
||||
1. The Worker generates a signing public/private Ed25519 keypair and an
|
||||
encryption public/private X25519 keypair, along with a registration nonce,
|
||||
and provides these values in a bundle to the operator or orchestration
|
||||
system. The bundle is signed with the Worker's private Ed25519 key (signing
|
||||
ensures that a Meddler-in-the-Middle (MITM) that is able to snoop traffic
|
||||
will be unable to masquerade as the Worker in requests sent to the
|
||||
Controller, due to lacking the Worker's private signing key; as a result it
|
||||
should never be properly registered or sent sessions to proxy).
|
||||
|
||||
2. The operator or orchestration system submits this bundle to a Controller in
|
||||
the cluster via an authenticated and authorized API call, requesting that a
|
||||
Worker resource be created tied to the given key information.
|
||||
|
||||
3. The Controller creates a Worker resource and associates it to the given key
|
||||
material. The Controller also signs a _client-only_ certificate
|
||||
authenticating the Worker's signing key and generates its own encryption
|
||||
public/private keypair specific to that Worker.
|
||||
|
||||
4. The Worker requests to its configured upstream(s) to fetch its issued
|
||||
credentials. It provides its public keys and original registration nonce in
|
||||
the request, which is signed via the Worker's private Ed25519 key. (Here
|
||||
again this means that a MitM cannot masquerade as the Worker due to lacking
|
||||
the signing key.) If the configured upstream is a Controller, it can respond
|
||||
directly; otherwise the request is relayed up to the cluster Controllers.
|
||||
|
||||
5. A Controller receiving the request validates that the provided nonce matches
|
||||
the nonce in the bundle provided by the operator/orchestration system in step
|
||||
2, and that the keys also match. If so, the Controller uses its
|
||||
Worker-specific encryption private key and the Worker's encryption public key
|
||||
to derive a shared symmetric encryption key, and uses it to encrypt the
|
||||
Worker certificate, its CA certifciate, and the nonce, and returns it to the
|
||||
Worker along with its encryption public key.
|
||||
|
||||
6. The Worker uses the given Controller encryption public key and its private
|
||||
key to derive the shared symmetric key; confirms it can decrypt the returned
|
||||
bundle; and validates the nonce, storing the issued certificate and CA
|
||||
certificate.
|
||||
|
||||
#### PKI-Based Session Establishment
|
||||
|
||||
Using the stored credentials, a PKI-based worker establishes a session as
|
||||
follows:
|
||||
|
||||
1. The Worker initiates a TLS connection to an upstream, presenting its TLS
|
||||
certificate along with a signed bundle containing a nonce.
|
||||
|
||||
2. The upstream requests a just-in-time server certificate (remember,
|
||||
certificates issued during registration are client-only), either directly (if
|
||||
a Controller) or via a proxied request to a Controller (if another Worker).
|
||||
The request conveys the Worker's nonce as well as the key ID from the client
|
||||
certificate.
|
||||
|
||||
3. A cluster Controller validates the key ID to ensure it is a registered
|
||||
worker, then creates a certificate with a short validation period that embeds
|
||||
the Worker's nonce, signed with the cluster's CA certificate. The Controller
|
||||
issuing this certificate has now authenticated the incoming Worker to the
|
||||
upstream, as the Controller has now vouched for the validity of the Worker
|
||||
tied to the client certificate. (Technically client certificate verification
|
||||
happens later in the TLS handshake, but conceptually this is when the
|
||||
incoming Worker is authenticated to the upstream.)
|
||||
|
||||
4. The upstream presents this server certificate to the Worker. The Worker
|
||||
validates that its nonce is embedded in the certificate and that the
|
||||
certificate chain can be validated to one of its saved CAs. This
|
||||
authenticates the upstream to the incoming Worker, since the trusted root has
|
||||
issued a new certificate containing the expected nonce and provided it to the
|
||||
upstream.
|
||||
|
||||
5. The TLS connection is now established, and the upstream can handle the Worker
|
||||
protocol.
|
||||
|
||||
#### PKI-Based Credential Rotation
|
||||
|
||||
Periodically, a PKI-based Worker will trigger rotation of its credentials. The
|
||||
mechanism is as follows:
|
||||
|
||||
1. The Worker generates a new signing public/private Ed25519 keypair and a new
|
||||
encryption X25519 public/private keypair.
|
||||
|
||||
2. The Worker creates a request to fetch new credentials from the Controller,
|
||||
providing its new public keys and an operation nonce in the request,
|
||||
encrypted with the current shared symmetric encryption key via the current
|
||||
X25519 parameters. As only the Controllers and the Worker can derive this
|
||||
shared symmetric key, the Worker knows that for the request to be satisfied
|
||||
it must be handled by an already-trusted Controller.
|
||||
|
||||
3. The Controller decrypts the bundle and registers the new key information to
|
||||
the Worker resource. It generates a new certificate and encryption
|
||||
public/private keypair and returns the certificate, current CA, operation
|
||||
nonce, and encryption public key to the worker. All but the encryption public
|
||||
key are encrypted with the symmetric key derived from the new Controller
|
||||
encryption private key/new Worker encryption public key.
|
||||
|
||||
4. This information is itself encrypted with the existing symmetric encryption
|
||||
key, and this value returned to the Worker.
|
||||
|
||||
5. The Worker decrypts the outer bundle with its current information, uses that
|
||||
to retrieve an authenticated new encryption public key from the Controller,
|
||||
then uses that with its new encryption private key to derive the new shared
|
||||
symmetric encryption key. That new key is used to decrypt the rest of the
|
||||
parameters, and the nonce is checked to ensure that the response is for the
|
||||
current operation started by the Worker in step 1.
|
||||
|
||||
6. The Worker has validated that a trusted Controller provided the new
|
||||
certificate information and encryption parameters and that those parameters
|
||||
can be used to successfully derive a shared symmetric encryption key. The
|
||||
Worker saves the new credentials and uses them going forwardl
|
||||
|
||||
### KMS-Based Worker Authentication
|
||||
|
||||
Workers can take advantage of the [KMS](/docs/concepts/security/data-encryption)
|
||||
key designated for `worker-auth` within Boundary's configuration file, which
|
||||
must point to the same key on the KMS for both the Controller and the Worker.
|
||||
Security of the connection relies on secure transmission of a single set of
|
||||
allowed TLS parameters, which forms the entire allowable CA chain for the
|
||||
connection.
|
||||
|
||||
TLS establishment is performed as follows:
|
||||
|
||||
1. The Worker generates a TLS certificate acting as a self-contained chain, as
|
||||
well as a nonce. The generated key type is currently Ed25519. The certificate is
|
||||
valid for a total of 2.5 minutes: thirty seconds before the current time (to
|
||||
allow for some minor clock drift) and two minutes after (to allow time to
|
||||
establish the connection).
|
||||
|
||||
2. The Worker marshals the TLS chain and nonce and encrypts the resulting bytes
|
||||
via the shared KMS. This value is marshaled and split into chunks.
|
||||
|
||||
3. The Worker establishes a TLS 1.3 connection to the Controller. The encrypted
|
||||
value is transmitted to the Controller via the TLS ALPN field as numbered
|
||||
chunks.
|
||||
|
||||
4. The Controller reads the chunks and reassembles them into the original
|
||||
encrypted value.
|
||||
|
||||
5. The Controller decrypts this value via the shared KMS. If successful, the
|
||||
Controller validates that the nonce is not known to ensure that this is not a
|
||||
replay. The nonce value is checked against and stored into the database,
|
||||
ensuring that nonce replay cannot occur across controllers.
|
||||
|
||||
6. The Controller uses the decrypted parameters to configures its TLS stack with
|
||||
the same certificate and key.
|
||||
|
||||
7. The connection is mutually authenticated; on each end, only the single
|
||||
self-signed CA certificate that was securely transmitted is configured as a
|
||||
valid root CA for validation checking.
|
||||
@@ -9,8 +9,8 @@ description: |-
|
||||
|
||||
Boundary has multiple mechanisms to ensure secure end-to-end behavior of the
|
||||
system. A key part of this is [support for various Key Management
|
||||
Systems](/docs/configuration/kms) that protect the base encryption keys used for
|
||||
various functions. This page describes the various KMS key purposes that
|
||||
Systems](/docs/configuration/kms) that protect the base encryption keys used
|
||||
for various functions. This page describes the various KMS key purposes that
|
||||
Boundary supports and how they are used within the system.
|
||||
|
||||
~> Boundary does not currently support rotation of its internal keys, but this
|
||||
|
||||
@@ -1,23 +1,24 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Server Configuration
|
||||
page_title: Overview/Top-Level Parameters
|
||||
description: Boundary configuration reference.
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
[listener]: /docs/configuration/listener
|
||||
[telemetry]: /docs/configuration/telemetry
|
||||
[controller]: /docs/configuration/controller
|
||||
[worker]: /docs/configuration/worker
|
||||
[kms]: /docs/configuration/kms
|
||||
[plugins]: /docs/configuration/plugins
|
||||
|
||||
Outside of development mode, Boundary controllers and workers are configured using a file.
|
||||
The format of this file is [HCL](https://github.com/hashicorp/hcl). In this section you'll find
|
||||
Outside of development mode, Boundary controllers and workers are configured
|
||||
using a file. The format of this file is
|
||||
[HCL](https://github.com/hashicorp/hcl). In this section you'll find
|
||||
configuration block examples for Boundary controllers and workers.
|
||||
|
||||
After the configuration is written, use the `-config` flag to specify a local path to the file.
|
||||
After the configuration is written, use the `-config` flag to specify a local
|
||||
path to the file.
|
||||
|
||||
## Parameters
|
||||
|
||||
@@ -65,12 +66,18 @@ After the configuration is written, use the `-config` flag to specify a local pa
|
||||
LimitMEMLOCK=infinity
|
||||
```
|
||||
|
||||
- `log_level` `(string: "info")` – Specifies the log level to use; overridden by
|
||||
CLI and env var parameters. Supported log levels: Trace, Debug, Error, Warn, Info.
|
||||
- `log_level` `(string: "info")` – (Deprecated: this is being phased out in
|
||||
favor of observability and is currently only used as a backup if eventing
|
||||
fails.) Specifies the log level to use; overridden by CLI and env var
|
||||
parameters. Supported log levels: Trace, Debug, Error, Warn, Info.
|
||||
|
||||
- `log_format` `(string: "")` – Specifies the log format to use; overridden by
|
||||
CLI and env var parameters. Supported log formats: `"standard"`, `"json"`.
|
||||
- `log_format` `(string: "")` – (Deprecated: this is being phased out in favor
|
||||
of observability and is currently only used as a backup if eventing fails.)
|
||||
Specifies the log format to use; overridden by CLI and env var parameters.
|
||||
Supported log formats: `"standard"`, `"json"`.
|
||||
|
||||
## Example Configurations
|
||||
|
||||
For complete example configurations see the sections for [controller](/docs/configuration/controller) and [worker](/docs/configuration/worker).
|
||||
For complete example configurations see the sections for
|
||||
[controller](/docs/configuration/controller) and
|
||||
[worker](/docs/configuration/worker).
|
||||
@@ -1,120 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Worker - Configuration
|
||||
description: |-
|
||||
The worker stanza configures worker-specific parameters.
|
||||
---
|
||||
|
||||
# `worker` Stanza
|
||||
|
||||
The `worker` stanza configures Boundary worker-specific parameters.
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
name = "example-worker"
|
||||
description = "An example worker"
|
||||
public_addr = "5.1.23.198"
|
||||
}
|
||||
```
|
||||
|
||||
- `name` - Specifies a unique name of this worker within the Boundary
|
||||
cluster. This value can be a direct name string, can refer to a file on disk
|
||||
(file://) from which an name will be read; or an env var (env://) from which
|
||||
the name will be read.
|
||||
|
||||
- `description` - Specifies a friendly description of this worker.
|
||||
This value can be a direct description string, can refer to a file on disk
|
||||
(file://) from which a description will be read; or an env var (env://) from
|
||||
which the description will be read.
|
||||
|
||||
- `public_addr` - Specifies the public host or IP address (and optionally port)
|
||||
at which the worker can be reached _by clients for proxying_. This defaults to
|
||||
the address of the listener marked for `proxy` purpose. This is especially
|
||||
useful for cloud environments that do not bind a publicly accessible IP to a NIC
|
||||
on the host directly, such as an Amazon EIP. This value can be a direct address string,
|
||||
can refer to a file on disk (file://) from which an address will be read;
|
||||
an env var (env://) from which the address will be read;
|
||||
or a [go-sockaddr template](https://godoc.org/github.com/hashicorp/go-sockaddr/template).
|
||||
|
||||
- `initial_upstreams` - A list of hosts/IP addresses and optionally ports for reaching
|
||||
controllers or workers. The port will default to :9201 if not specified. This value can be
|
||||
a direct access string array with the addresses, or it can refer to a file on
|
||||
disk (file://) from which the addresses will be read, or an env var (env://) from
|
||||
which the addresses will be read. When using env or file, their contents
|
||||
must formatted as a JSON array: `["127.0.0.1", "192.168.0.1", "10.0.0.1"]`
|
||||
|
||||
- `tags` - A map of key-value pairs where values are an array of strings. Most
|
||||
commonly used for [filtering](/docs/concepts/filtering) targets a worker can
|
||||
proxy via [worker tags](/docs/concepts/filtering/worker-tags). On `SIGHUP`, the
|
||||
tags set here will be re-parsed and new values used. It can also be a string
|
||||
referring to a file on disk (file://) or an env var (env://).
|
||||
|
||||
## KMS Configuration
|
||||
|
||||
Workers require a KMS block designated for `worker-auth`. This is the KMS configuration for
|
||||
authentication between the workers and controllers and must be present. Example (not safe for production!):
|
||||
|
||||
```hcl
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
```
|
||||
|
||||
This configuration must be the same for the worker-auth configuration for the controller if you're
|
||||
running the controller and worker as separate servers.
|
||||
|
||||
And optionally, a KMS stanza for configuration encryption purpose:
|
||||
|
||||
```hcl
|
||||
# Configuration encryption block: decrypts sensitive values in the
|
||||
# configuration file. See `boundary config [encrypt|decrypt] -h`.
|
||||
kms "aead" {
|
||||
purpose = "config"`
|
||||
aead_type = "aes-gcm"
|
||||
key = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
|
||||
}
|
||||
```
|
||||
|
||||
Boundary supports many kinds of KMS integrations. For a complete guide to all available
|
||||
KMS types, see our [KMS documentation](/docs/configuration/kms).
|
||||
|
||||
# Complete Configuration Example
|
||||
|
||||
```hcl
|
||||
listener "tcp" {
|
||||
purpose = "proxy"
|
||||
tls_disable = true
|
||||
address = "127.0.0.1"
|
||||
}
|
||||
|
||||
worker {
|
||||
# Name attr must be unique across workers
|
||||
name = "demo-worker-1"
|
||||
description = "A default worker created demonstration"
|
||||
|
||||
# Workers must be able to reach controllers on :9201
|
||||
controllers = [
|
||||
"10.0.0.1",
|
||||
"10.0.0.2",
|
||||
"10.0.0.3",
|
||||
]
|
||||
|
||||
public_addr = "myhost.mycompany.com"
|
||||
|
||||
tags {
|
||||
type = ["prod", "webservers"]
|
||||
region = ["us-east-1"]
|
||||
}
|
||||
}
|
||||
|
||||
# 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"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: KMS Worker Configuration
|
||||
description: |-
|
||||
KMS worker-specific parameters.
|
||||
---
|
||||
|
||||
|
||||
## KMS Worker Configuration
|
||||
|
||||
KMS Workers require a `name` field. This specifies a unique name of this worker within the Boundary cluster.
|
||||
The `name` value can be:
|
||||
- a direct name string (must be all lowercase)
|
||||
- a reference to a file on disk (`file://`) from which the name is read
|
||||
- an env var (`env://`) from which the name is read.
|
||||
|
||||
~> **Note:** Changing the `name` results in the creation of a new worker in the
|
||||
cluster and assignment of a new worker ID.
|
||||
|
||||
KMS Workers accept an optional `description` field. The `description` value can be:
|
||||
- a direct description string
|
||||
- a reference to a file on disk (`file://`) from which the name is read
|
||||
- an env var (`env://`) from which the name is read.
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
name = "example-worker"
|
||||
description = "An example worker"
|
||||
public_addr = "5.1.23.198"
|
||||
}
|
||||
```
|
||||
|
||||
KMS Workers also require a KMS block designated for `worker-auth`. This is the KMS configuration for
|
||||
authentication between the workers and controllers and must be present. Example (not safe for production!):
|
||||
|
||||
```hcl
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
```
|
||||
|
||||
This configuration must be the same for the worker-auth configuration for the controller if you're
|
||||
running the controller and worker as separate servers.
|
||||
|
||||
Optionally, a KMS stanza for configuration encryption purpose can also be specified:
|
||||
|
||||
```hcl
|
||||
# Configuration encryption block: decrypts sensitive values in the
|
||||
# configuration file. See `boundary config [encrypt|decrypt] -h`.
|
||||
kms "aead" {
|
||||
purpose = "config"`
|
||||
aead_type = "aes-gcm"
|
||||
key = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
|
||||
}
|
||||
```
|
||||
|
||||
Boundary supports many kinds of KMS integrations. For a complete guide to all available
|
||||
KMS types, see our [KMS documentation](/docs/configuration/kms).
|
||||
|
||||
# Complete Configuration Example
|
||||
|
||||
```hcl
|
||||
listener "tcp" {
|
||||
purpose = "proxy"
|
||||
tls_disable = true
|
||||
address = "127.0.0.1"
|
||||
}
|
||||
|
||||
worker {
|
||||
# Name attr must be unique across workers
|
||||
name = "demo-worker-1"
|
||||
description = "A default worker created for demonstration"
|
||||
|
||||
# Workers must be able to reach upstreams on :9201
|
||||
initial_upstreams = [
|
||||
"10.0.0.1",
|
||||
"10.0.0.2",
|
||||
"10.0.0.3",
|
||||
]
|
||||
|
||||
public_addr = "myhost.mycompany.com"
|
||||
|
||||
tags {
|
||||
type = ["prod", "webservers"]
|
||||
region = ["us-east-1"]
|
||||
}
|
||||
}
|
||||
|
||||
# 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"
|
||||
}
|
||||
```
|
||||
|
||||
[`initial_upstreams`](/docs/configuration/worker/overview#initial_upstreams)
|
||||
are used to connect to upstream Boundary clusters.
|
||||
|
||||
## Further Reading
|
||||
|
||||
For more on how `tags{}` in the above configuration are used to facilitate
|
||||
routing to the correct target, refer to the [Worker
|
||||
Tags](/docs/concepts/filtering/worker-tags) page.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Worker - Overview
|
||||
description: |-
|
||||
The worker stanza configures worker-specific parameters.
|
||||
---
|
||||
|
||||
# `worker` Stanza
|
||||
|
||||
The `worker` stanza configures Boundary worker-specific parameters. Boundary
|
||||
supports two different types of workers, differentiated by their means of
|
||||
authentication to Boundary:
|
||||
- [KMS Workers][] use a shared KMS to authenticate with controllers
|
||||
- [PKI Workers][] use certificates issued by Boundary to authenticate with controllers
|
||||
|
||||
Different worker types have different configuration requirements, but share the common worker parameters listed below.
|
||||
|
||||
## Common Worker Parameters
|
||||
The following fields are supported for all worker types:
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
public_addr = "5.1.23.198"
|
||||
|
||||
initial_upstreams = [
|
||||
"10.0.0.1",
|
||||
"10.0.0.2",
|
||||
]
|
||||
|
||||
tags {
|
||||
type = ["prod", "webservers"]
|
||||
region = ["us-east-1"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `public_addr` - Specifies the public host or IP address (and optionally port)
|
||||
at which the worker can be reached _by clients for proxying_. This defaults to
|
||||
the address of the listener marked for `proxy` purpose. This is especially
|
||||
useful for cloud environments that do not bind a publicly accessible IP to a NIC
|
||||
on the host directly, such as an Amazon EIP.
|
||||
|
||||
This value can reference any of the following:
|
||||
- a direct address string
|
||||
- a file on disk (file://) from which an address will be read
|
||||
- an env var (env://) from which the address will be read
|
||||
- a [go-sockaddr template](https://godoc.org/github.com/hashicorp/go-sockaddr/template)
|
||||
|
||||
- `initial_upstreams` - A list of hosts/IP addresses and optionally ports for
|
||||
reaching the boundary cluster. The port will default to `:9201` if not
|
||||
specified. This value can be a direct access string array with the addresses,
|
||||
or it can refer to a file on disk (`file://`) from which the addresses will be
|
||||
read, or an env var (`env://`) from which the addresses will be read. When using
|
||||
env or file, their contents must formatted as a JSON array: `["127.0.0.1",
|
||||
"192.168.0.1", "10.0.0.1"]`
|
||||
|
||||
- `tags` - A map of key-value pairs where values are an array of strings. Most
|
||||
commonly used for [filtering](/docs/concepts/filtering) targets a worker can
|
||||
proxy via [worker tags](/docs/concepts/filtering/worker-tags). On `SIGHUP`, the
|
||||
tags set here will be re-parsed and new values used. It can also be a string
|
||||
referring to a file on disk (`file://`) or an env var (`env://`).
|
||||
|
||||
[kms workers]: /docs/configuration/worker/kms-worker
|
||||
[pki workers]: /docs/configuration/worker/pki-worker
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: PKI Worker Configuration
|
||||
description: |-
|
||||
PKI worker-specific parameters.
|
||||
---
|
||||
|
||||
|
||||
## PKI Worker Configuration
|
||||
PKI Workers authenticate to Boundary using a certificate-based method, allowing
|
||||
for worker deployment without using a shared KMS.
|
||||
|
||||
PKI Workers require an accessible directory defined by `auth_storage_path` for
|
||||
credential storage.
|
||||
|
||||
Example (not safe for production!):
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
auth_storage_path="/boundary/demo-worker-1"
|
||||
initial_upstreams = ["10.0.0.1"]
|
||||
}
|
||||
```
|
||||
|
||||
~> **Note:** `name` and `description` fields are not valid config fields for PKI
|
||||
workers. These fields are only valid for [KMS Workers][]. `name` and
|
||||
`description` can only be set for PKI workers through the API.
|
||||
|
||||
# Complete Configuration Example
|
||||
|
||||
```hcl
|
||||
listener "tcp" {
|
||||
purpose = "proxy"
|
||||
tls_disable = true
|
||||
address = "127.0.0.1"
|
||||
}
|
||||
|
||||
worker {
|
||||
# Path for worker storage. Must be unique across workers
|
||||
auth_storage_path="/boundary/demo-worker-1"
|
||||
|
||||
# Workers typically need to reach upstreams on :9201
|
||||
initial_upstreams = [
|
||||
"10.0.0.1",
|
||||
"10.0.0.2",
|
||||
"10.0.0.3",
|
||||
]
|
||||
|
||||
public_addr = "myhost.mycompany.com"
|
||||
|
||||
tags {
|
||||
type = ["prod", "webservers"]
|
||||
region = ["us-east-1"]
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
```
|
||||
[kms workers]: /docs/configuration/worker/kms-worker
|
||||
@@ -7,15 +7,36 @@ description: |-
|
||||
|
||||
## 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). The host sets for this target
|
||||
contain the default host, which has the address `127.0.0.1`. When `boundary
|
||||
connect` is executed against this target, the single available host will be
|
||||
selected and a local authenticated proxy to the host is established on the
|
||||
target's default port (`127.0.0.1:22`).
|
||||
The [Quick setup
|
||||
wizard](/docs/getting-started/deploy-and-login#login-to-hcp-boundary)
|
||||
is the fastest way to onboard a target to HCP Boundary.
|
||||
|
||||
|
||||
|
||||
A `tcp` target with a default port of `22` (the default SSH port using TCP) is
|
||||
recommended for an initial target. If using the Quick setup, a sample host set
|
||||
called **QA Databases** will contain the **CRM Database** host, with the Address
|
||||
provided during setup. When `boundary connect` is executed against the **CRM
|
||||
Database target**, the single available host will be selected and a local
|
||||
authenticated proxy to the host is established on the target's default port.
|
||||
|
||||
|
||||
|
||||
To connect to the initial CRM Database target:
|
||||
|
||||
1. Copy the **CRM Database target ID** (such as `ttcp_eTcZMueUYv`).
|
||||
|
||||
1. Open a terminal session. Export the Boundary **Origin URL** as an environment
|
||||
variable.
|
||||
|
||||
```shell-session
|
||||
$ export BOUNDARY_ADDR=<boundary-origin-url>
|
||||
```
|
||||
$ boundary connect -target-id ttcp_1234567890
|
||||
|
||||
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 utilize. In
|
||||
@@ -43,16 +64,16 @@ filling in the local address and port. An expected host ID is set to avoid
|
||||
warnings on future connections when a different port is allocated automatically.
|
||||
A host key must still be accepted upon first connect.
|
||||
|
||||
```
|
||||
$ boundary connect ssh -target-id ttcp_1234567890
|
||||
```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 will be passed
|
||||
to the executed client. For instance:
|
||||
|
||||
```
|
||||
$ boundary connect ssh -target-id ttcp_1234567890 -- -l some-other-user
|
||||
```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
|
||||
@@ -83,7 +104,7 @@ 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"
|
||||
```
|
||||
|
||||
@@ -107,8 +128,8 @@ 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 `--`:
|
||||
|
||||
```
|
||||
$ boundary connect ssh -target-id ttcp_1234567890 -- -l myuser -i ~/.ssh/identity
|
||||
```shell-session
|
||||
$ boundary connect ssh -target-id ttcp_eTcZMueUYv -- -l myuser -i ~/.ssh/identity
|
||||
```
|
||||
|
||||
You also have access to some templated values that are substituted into the
|
||||
@@ -126,29 +147,29 @@ 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`:
|
||||
|
||||
```
|
||||
$ boundary targets update tcp -default-port 443 -id ttcp_1234567890
|
||||
```shell-session
|
||||
$ boundary targets update tcp -default-port 443 -id ttcp_eTcZMueUYv
|
||||
|
||||
Target information:
|
||||
Created Time: Fri, 25 Sep 2020 18:35:47 PDT
|
||||
Description: Provides an initial target in Boundary
|
||||
ID: ttcp_1234567890
|
||||
Name: Generated target
|
||||
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, 25 Sep 2020 18:36:18 PDT
|
||||
Updated Time: Fri, 17 June 2022 19:15:17 PDT
|
||||
Version: 2
|
||||
|
||||
Scope:
|
||||
ID: p_1234567890
|
||||
Name: Generated project scope
|
||||
Parent Scope ID: o_1234567890
|
||||
ID: p_A4jfDjZ9jf
|
||||
Name: Sample project created by quick setup
|
||||
Parent Scope ID: o_B1xISmpJ5Y
|
||||
Type: project
|
||||
|
||||
Host Sets:
|
||||
Host Catalog ID: hcst_1234567890
|
||||
ID: hsst_1234567890
|
||||
Host Catalog ID: hcst_YgIU0sHxXp
|
||||
ID: hsst_pp6f2hfRYB
|
||||
|
||||
Attributes:
|
||||
Default Port: 443
|
||||
@@ -159,8 +180,8 @@ 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:
|
||||
|
||||
```
|
||||
$ boundary connect -exec curl -target-id ttcp_1234567890 \
|
||||
```shell-session
|
||||
$ boundary connect -exec curl -target-id ttcp_eTcZMueUYv \
|
||||
-- -vvsL --output /dev/null hashicorp.com
|
||||
|
||||
* Trying 76.76.21.21...
|
||||
@@ -178,8 +199,8 @@ 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):
|
||||
|
||||
```
|
||||
$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_1234567890
|
||||
```shell-session
|
||||
$ boundary connect ssh -style putty -exec putty.exe -target-id ttcp_eTcZMueUYv
|
||||
```
|
||||
|
||||
## Connect using Desktop Client
|
||||
@@ -192,7 +213,7 @@ proxy details.
|
||||
playsInline
|
||||
autoPlay
|
||||
loop
|
||||
class="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
className="boundary-clickthrough-video boundary-clickthrough-desktop-video"
|
||||
>
|
||||
<source
|
||||
type="video/mp4"
|
||||
@@ -202,5 +223,6 @@ proxy details.
|
||||
|
||||
## Next Steps
|
||||
|
||||
See our [basic administration workflows](https://learn.hashicorp.com/collections/boundary/basic-administration) for in depth discussion on managing scopes, targets,
|
||||
identities, and sessions.
|
||||
See our [basic administration
|
||||
workflows](https://learn.hashicorp.com/collections/boundary/hcp-administration)
|
||||
for in depth discussion on managing scopes, targets, identities, and sessions.
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Deploy and Login
|
||||
description: |-
|
||||
How to deploy HCP Boundary services and login for the first time.
|
||||
---
|
||||
|
||||
# Deploy an HCP Boundary Instance
|
||||
|
||||
HCP Boundary is a fully-managed cloud-based workflow. It enables secure access
|
||||
to remote hosts and critical systems across cloud service catalogs, on-premises
|
||||
infrastructure, and Kubernetes clusters without needing to manage any of the
|
||||
underlying systems or operations.
|
||||
|
||||
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 (Beta)** 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.
|
||||
|
||||
1. Click **Auth Methods**.
|
||||
|
||||
1. Click the **copy icon** for the Password **Auth Method ID**. The ID is needed to
|
||||
authenticate to HCP Boundary using the CLI.
|
||||
|
||||
<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 **Origin URL**.
|
||||
|
||||
1. Open a terminal session and set the `BOUNDARY_ADDR` environment variable to
|
||||
the copied origin URL.
|
||||
|
||||
```shell-session
|
||||
$ export BOUNDARY_ADDR=<boundary-origin-url>
|
||||
```
|
||||
|
||||
1. Log in with the administrator credentials you created when you deployed the
|
||||
HCP Boundary instance.
|
||||
|
||||
```shell-session
|
||||
$ boundary authenticate password \
|
||||
-auth-method-id=COPIED_AUTH_ID \
|
||||
-login-name=ADMIN_USERNAME \
|
||||
-password=ADMIN_PASSWORD
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Desktop Client">
|
||||
|
||||
|
||||
[Boundary Desktop](https://www.boundaryproject.io/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 origin 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 **Origin URL**.
|
||||
|
||||
You can find your environment’s origin 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 **Origin
|
||||
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-origin-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 **Origin 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>
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
||||
See [connecting to your first target](/docs/getting-started/connect-to-target)
|
||||
for how to use HCP Boundary to run your first SSH session.
|
||||
@@ -10,34 +10,12 @@ Before getting started with Boundary, it's important to understand a few key con
|
||||
|
||||
## Requirements
|
||||
|
||||
The examples in Getting Started all revolve around running in `dev mode`. There are a few requirements for running dev mode:
|
||||
The Getting Started section uses HCP Boundary, a HashiCorp hosted and fully-managed version of the Boundary product.
|
||||
|
||||
1. [Docker](https://docs.docker.com/get-docker/) is installed
|
||||
1. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) is available or a local image cache is available
|
||||
1. A [Boundary binary](https://www.boundaryproject.io/downloads) in your `$PATH`
|
||||
1. Optionally, an [installation of Boundary Desktop](https://learn.hashicorp.com/tutorials/boundary/getting-started-desktop-app) if you want to use the desktop examples
|
||||
To get started with HCP Boundary, users need:
|
||||
|
||||
## What is Dev Mode?
|
||||
- A [HashiCorp Cloud Platform](https://portal.cloud.hashicorp.com/sign-up) account
|
||||
- A [Boundary binary](https://www.boundaryproject.io/downloads) in your `$PATH`
|
||||
- Optionally, an [installation of Boundary Desktop](https://learn.hashicorp.com/tutorials/boundary/getting-started-desktop-app)
|
||||
|
||||
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 [Production Installation](/docs/installing/high-availability) 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 org [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`.
|
||||
|
||||
The default ID suffixes are overridable or can be 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.
|
||||
If you prefer to Get Started on your local machine, refer to [Run and Login in Dev Mode](/docs/oss/installing/run-and-login). For more information on Boundary OSS and self-managed installations, refer to [Boundary OSS](/docs/oss/index).
|
||||
@@ -50,12 +50,6 @@ Example controller configuration:
|
||||
# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
|
||||
disable_mlock = true
|
||||
|
||||
telemetry {
|
||||
# prometheus is not currently implemented
|
||||
prometheus_retention_time = "24h"
|
||||
disable_hostname = true
|
||||
}
|
||||
|
||||
# Controller configuration block
|
||||
controller {
|
||||
# This name attr must be unique!
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Operating Boundary
|
||||
description: |-
|
||||
Operational tasks in Boundary.
|
||||
---
|
||||
|
||||
# Maintaining and Operating Boundary
|
||||
|
||||
Visibility into various components of Boundary plays an important role in ensuring the health of its controllers and workers. While additional monitoring components are planned for subsequent Boundary releases, metrics for controllers and workers can now be exported and then collected by Prometheus. Metrics provide insight into the current state of a Boundary deployment by enabling the diagnosis of deployed controllers and workers. Enabling metrics assists in the detection and mitigation of anomalies in a deployment.
|
||||
|
||||
These docs describe the available metrics and the naming and labeling standards used. Additionally, the health of controllers can be monitored using the `/health` endpoint. The health endpoint is enabled by defining a listener in Boundary's configuration file, and a health response may be configured to add a shutdown grace period process.
|
||||
|
||||
* Refer to the [Metrics](/docs/operations/metrics) documentation to learn more about Boundary metrics.
|
||||
* Refer to the [Health Endpoint](/docs/operations/health) documentation to learn more about Boundary health endpoints.
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,27 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: OSS Boundary
|
||||
description: An introduction to OSS Boundary
|
||||
---
|
||||
|
||||
# Boundary OSS
|
||||
|
||||
Boundary provides secure remote access to critical systems with fine-grained
|
||||
authorizations based on trusted identities. While HCP Boundary provides a
|
||||
managed solution, Boundary OSS is a self-managed distribution that organizations
|
||||
can deploy on-premise to manage access to infrastructure endpoints. The source
|
||||
code for Boundary OSS is freely available on GitHub. The following sections
|
||||
contain information on the use case for Boundary and how to install and
|
||||
configure self-managed Boundary environments.
|
||||
|
||||
Traditional approaches like SSH bastion hosts or VPNs require distributing and
|
||||
managing credentials, configuring network controls like firewalls, and exposing
|
||||
the private network. Boundary OSS provides secure access to hosts and critical
|
||||
systems without having to manage credentials or expose your network, and is
|
||||
entirely open source.
|
||||
|
||||
Boundary OSS is designed to be straightforward to understand, highly scalable,
|
||||
and resilient. It can run in clouds, on-premise, or within secure enclaves.
|
||||
Boundary does not require an agent to be installed on the end host.
|
||||
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Connect to Dev Mode 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). The host sets for this target
|
||||
contain the default host, which has the address `127.0.0.1`. When `boundary
|
||||
connect` is executed against this target, the single available host will be
|
||||
selected and a local authenticated proxy to the host is established on the
|
||||
target's default port (`127.0.0.1:22`).
|
||||
|
||||
```shell-session
|
||||
$ boundary connect -target-id ttcp_1234567890
|
||||
```
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
Host Sets:
|
||||
Host Catalog ID: hcst_1234567890
|
||||
ID: hsst_1234567890
|
||||
|
||||
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](https://learn.hashicorp.com/collections/boundary/oss-administration)
|
||||
for in depth discussion on managing scopes, targets, identities, and sessions.
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: What is Dev Mode?
|
||||
description: Getting started with Boundary OSS in Dev mode
|
||||
---
|
||||
|
||||
# What is Dev Mode?
|
||||
|
||||
Before getting started with Boundary OSS, 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.
|
||||
|
||||
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](/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](/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](/docs/concepts/domain-model/auth-methods) with a
|
||||
default auth method ID of `ampw_1234567890`.
|
||||
1. An OIDC [auth method](/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](/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`.
|
||||
|
||||
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](https://www.boundaryproject.io/downloads) in your `$PATH`
|
||||
- _Optionally_, an [installation of Boundary
|
||||
Desktop](https://learn.hashicorp.com/tutorials/boundary/oss-getting-started-desktop-app)
|
||||
if you want to use the desktop examples
|
||||
File renamed without changes.
+1
-1
@@ -9,4 +9,4 @@ description: |-
|
||||
|
||||
This section covers installing Boundary for different modes of operation and across different environments
|
||||
|
||||
For community-supported reference architectures, please see [Reference Architectures](/docs/installing/reference-architectures).
|
||||
For community-supported reference architectures, please see [Reference Architectures](/docs/oss/installing/reference-architectures).
|
||||
+1
-1
@@ -47,7 +47,7 @@ kms "aead" {
|
||||
```
|
||||
|
||||
In this example, we're using hardcoded AEAD keys, but in a real world non-dev deployment, you
|
||||
should use your cloud provider's KMS such as [AWS KMS](https://www.boundaryproject.io/docs/configuration/kms/awskms) to manage the keys Boundary
|
||||
should use your cloud provider's KMS such as [AWS KMS](/docs/configuration/kms/awskms) to manage the keys Boundary
|
||||
uses to encrypt sensitive information.
|
||||
|
||||
The KMS block we're focused on is the `recovery` block. This block specifies the key used to "recover" Boundary
|
||||
+1
-1
@@ -17,7 +17,7 @@ Boundary has only been tested on Postgres 11 or greater.
|
||||
|
||||
Boundary controllers must be able to reach Postgres.
|
||||
In non-HA configurations, this means Boundary servers;
|
||||
if you're running in [high availability](/docs/installing/high-availability),
|
||||
if you're running in [high availability](/docs/oss/installing/high-availability),
|
||||
then the controllers need access to the Postgres server infrastructure.
|
||||
Worker nodes never need access to the database.
|
||||
|
||||
File renamed without changes.
+15
-30
@@ -30,35 +30,19 @@ $ boundary authenticate password \
|
||||
-auth-method-id=ampw_1234567890
|
||||
```
|
||||
|
||||
If you are on Unix-like operating system (other than macOS/Darwin), you may get
|
||||
an error indicating that the token could not be stored, as the freedesktop.org
|
||||
Secret Service implementation is not always available. On these systems, you can
|
||||
work around this by installing `dbus-x11` and `gnome-keyring` using your package
|
||||
manager, then creating and unlocking the default keyring with the following,
|
||||
substituting in a password of your choice for "foobar" (but ending with `\n`).
|
||||
You can also avoid putting the password on the command line by running the
|
||||
`gnome-keyring-daemon` commands directly and entering in the password, followed
|
||||
by a newline (return) and an EOF (`Ctrl+D`).
|
||||
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.
|
||||
|
||||
- `eval "$(printf 'foobar\n' | gnome-keyring-daemon --unlock)"`
|
||||
- `eval "$(printf 'foobar\n' | gnome-keyring-daemon --start)"`
|
||||
|
||||
This would have to be run in each shell.
|
||||
|
||||
If you're unable to install these packages, or don't want to, you can tell the
|
||||
Boundary authenticate command to not save the token to the operating system's
|
||||
key manager by setting `-token-name=none` flag or `BOUNDARY_TOKEN_NAME=none` env
|
||||
variable when running `boundary authenticate`. You'll be responsible for setting
|
||||
the token in subsequent commands via `-token` flag or `BOUNDARY_TOKEN` env
|
||||
variable. An easy way to do this would be to use the `-format=json` flag along
|
||||
with `jq` to pull the token value out of the response and place it wherever you
|
||||
wish, then create a command alias for `boundary` that sources that value into
|
||||
the environment or the `-token` flag.
|
||||
|
||||
~> Token storage on \*nix systems has been more problematic than we expected.
|
||||
We're exploring alternatives. See the discussion on [this GitHub
|
||||
issue](https://github.com/hashicorp/boundary/issues/697#issuecomment-709448942)
|
||||
to track it and voice your thoughts.
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Admin Console">
|
||||
@@ -127,5 +111,6 @@ the Boundary server does not use TLS in development mode.
|
||||
|
||||
## Next Steps
|
||||
|
||||
See [connecting to your first target](/docs/getting-started/connect-to-target) for how
|
||||
to use Boundary to run your first SSH session.
|
||||
See [connecting to your first
|
||||
target](/docs/oss/installing/connect-to-dev-target) for how to use Boundary to
|
||||
run your first SSH session.
|
||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,27 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Operating Boundary
|
||||
description: |-
|
||||
Operational tasks in Boundary.
|
||||
---
|
||||
|
||||
# Maintaining and Operating Boundary
|
||||
|
||||
Visibility into various components of Boundary plays an important role in
|
||||
ensuring the health of its controllers and workers. While additional monitoring
|
||||
components are planned for subsequent Boundary releases, metrics for controllers
|
||||
and workers can now be exported and then collected by Prometheus. Metrics
|
||||
provide insight into the current state of a Boundary deployment by enabling the
|
||||
diagnosis of deployed controllers and workers. Enabling metrics assists in the
|
||||
detection and mitigation of anomalies in a deployment.
|
||||
|
||||
These docs describe the available metrics and the naming and labeling standards
|
||||
used. Additionally, the health of controllers can be monitored using the
|
||||
`/health` endpoint. The health endpoint is enabled by defining a listener in
|
||||
Boundary's configuration file, and a health response may be configured to add a
|
||||
shutdown grace period process.
|
||||
|
||||
* Refer to the [Metrics](/docs/oss/operations/metrics) documentation to learn
|
||||
more about Boundary metrics.
|
||||
* Refer to the [Health Endpoint](/docs/oss/operations/health) documentation to
|
||||
learn more about Boundary health endpoints.
|
||||
File renamed without changes.
@@ -19,7 +19,7 @@ Lastly, for instructions on how to upgrade an existing Boundary deployment to v0
|
||||
When enabled, event logs are the only type of logging Boundary performs, meaning standard system information and debug logs will no longer appear in stdout.
|
||||
The new structured event logs are filterable by event type and other expressions that users define. Legacy HCLog output is still supported through a user-configurable setting.
|
||||
|
||||
For more about event logging usage, see our [documentation](https://www.boundaryproject.io/docs/configuration/events/overview).
|
||||
For more about event logging usage, see our [documentation](/docs/configuration/events/overview).
|
||||
|
||||
**Credential CRUD operations for Administrative Console:** The 0.5.0 release enables administration to configure Vault credential libraries and Vault credential set resources through the administrative console.
|
||||
Vault credential resources allows users to create Boundary sessions with credentials brokered by a Vault deployment.
|
||||
|
||||
@@ -16,12 +16,12 @@ Lastly, for instructions on how to upgrade an existing Boundary deployment to v0
|
||||
## Boundary v0.8.0 Highlights
|
||||
|
||||
**Metrics and Health Endpoint:** Boundary is adding [Prometheus metrics](https://www.boundaryproject.io/docs/operations/metrics) to monitor the operations of workers and controllers,
|
||||
as well as a [health endpoint](https://www.boundaryproject.io/docs/operations/health) for controllers.
|
||||
as well as a [health endpoint](/docs/oss/operations/health) for controllers.
|
||||
|
||||
**Audit Event Logs:** We are expanding the audit event logs by increasing the captured [audit events](https://www.boundaryproject.io/docs/configuration/events/overview),
|
||||
**Audit Event Logs:** We are expanding the audit event logs by increasing the captured [audit events](/docs/configuration/events/overview),
|
||||
with support for sanitizing sensitive information from audit events. All of the events are now classified and events contain more usable data, with sensitive information redacted by default.
|
||||
|
||||
**UI Support for Worker Tags:** Users can now set and edit [worker tag](https://www.boundaryproject.io/docs/concepts/filtering/worker-tags) filters in the Boundary admin console.
|
||||
**UI Support for Worker Tags:** Users can now set and edit [worker tag](/docs/concepts/filtering/worker-tags) filters in the Boundary admin console.
|
||||
|
||||
**Performance Improvements:** We have implemented changes to improve performance on larger deployments; such as adding a refresh button in the admin console and desktop client,
|
||||
and improving response times listing sessions and targets. We plan to continue these efforts as Boundary users grow their deployments!
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: v0.9.0
|
||||
description: |-
|
||||
Boundary release notes for v0.9.0
|
||||
---
|
||||
|
||||
# [Boundary v0.9.0](https://www.boundaryproject.io/downloads)
|
||||
|
||||
The release notes below contain information about new functionality available in the Boundary v0.9.0 release.
|
||||
To see a granular record of when each item was merged into the Boundary project, please refer to the [Changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md).
|
||||
To learn about what Boundary consists of, we highly recommend you start at the [Getting Started Page](/docs/getting-started).
|
||||
|
||||
Lastly, for instructions on how to upgrade an existing Boundary deployment to v0.9.0, please review Boundary's [general upgrade guide](https://learn.hashicorp.com/tutorials/boundary/upgrade-version).
|
||||
|
||||
## Boundary v0.9.0 Highlights
|
||||
|
||||
**HCP Boundary Public Beta:** Boundary is coming to the HashiCorp Cloud Platform! HCP Boundary provides an easy way to securely access
|
||||
critical systems with fine-grained authorizations based on trusted identities. Boundary on HashiCorp Cloud Platform provides a fully managed,
|
||||
single workflow to securely connect to hosts and critical systems across Kubernetes clusters, cloud service catalogs, and on-premises infrastructure.
|
||||
You can now [try HCP Boundary](https://learn.hashicorp.com/collections/boundary/hcp-getting-started) for free during our [Public Beta](https://cloud.hashicorp.com/products/boundary).
|
||||
|
||||
**Self-Managed Workers:** With HCP Boundary, administrators have the option of setting up private, self-managed workers for infrastructure access. This provides the
|
||||
security of having privately managed workers while providing the low overhead of a managed service. Learn more about setting up self-managed workers
|
||||
[here](https://learn.hashicorp.com/tutorials/boundary/hcp-manage-workers).
|
||||
|
||||
**Worker Registration Enhancements:** Administrators now have a second method of authenticating workers, and we call these PKI Workers (the original
|
||||
authentication method is now called KMS Workers). PKI Workers authenticate to Boundary using a new certificate-based method, allowing for worker deployment
|
||||
without using a shared KMS.
|
||||
|
||||
**Static Credential Store:** In Boundary 0.9.0, we are introducing the static credential store, a basic
|
||||
[credential store](https://www.boundaryproject.io/docs/concepts/domain-model/credential-stores) that is native to Boundary. These credentials
|
||||
are encrypted and stored directly in Boundary. For users interested in integrated secrets management to Boundary targets, the new basic
|
||||
credential store removes the dependency on HashiCorp Vault. Currently, the static credential store only supports username/password type credentials. Note: If you
|
||||
wish to use the Desktop Client for credential brokering, version 1.4.4 and up is required.
|
||||
|
||||
**Admin UI Quickstart:** Users can now access a quickstart tool on the Admin UI which sets up a target along with a host, project, and organization.
|
||||
|
||||
## What's Changed
|
||||
|
||||
For more detailed information of all changes since 0.8.0, please refer to the [Changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md)
|
||||
|
||||
@@ -31,7 +31,10 @@ Boundary is an intelligent proxy that creates granular, identity-based access co
|
||||
|
||||
With the many varying infrastructure services and tooling used in increasingly dynamic environments, organizations must have secure access to all targets within and beyond their perimeter.
|
||||
|
||||
Boundary provides a simple way for verified users to have secure access to cloud and self-managed infrastructures without exposing your network or the use of managing credentials. Boundary is an open source workflow that enables just-in-time, role-based access for dynamic infrastructure.
|
||||
Boundary provides a simple way for verified users to have secure access to cloud
|
||||
and self-managed infrastructures without exposing your network or the use of
|
||||
managing credentials. Boundary is a workflow that enables just-in-time,
|
||||
role-based access for dynamic infrastructure.
|
||||
|
||||
## Boundary Use-Cases
|
||||
|
||||
|
||||
+216
-177
@@ -25,8 +25,8 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Run and Login",
|
||||
"path": "getting-started/run-and-login"
|
||||
"title": "Deploy and Login",
|
||||
"path": "getting-started/deploy-and-login"
|
||||
},
|
||||
{
|
||||
"title": "Connect to Target",
|
||||
@@ -35,61 +35,111 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Installing",
|
||||
"title": "Configuration",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "installing"
|
||||
"title": "Overview/Top-Level Parameters",
|
||||
"path": "configuration"
|
||||
},
|
||||
{
|
||||
"title": "Non-Dev Environments",
|
||||
"path": "installing/no-gen-resources"
|
||||
"title": "worker",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/worker/overview"
|
||||
},
|
||||
{
|
||||
"title": "KMS Workers",
|
||||
"path": "configuration/worker/kms-worker"
|
||||
},
|
||||
{
|
||||
"title": "PKI Workers",
|
||||
"path": "configuration/worker/pki-worker"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Systemd Install",
|
||||
"path": "installing/systemd"
|
||||
"title": "listener",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/listener"
|
||||
},
|
||||
{
|
||||
"title": "TCP",
|
||||
"path": "configuration/listener/tcp"
|
||||
},
|
||||
{
|
||||
"title": "Unix",
|
||||
"path": "configuration/listener/unix"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Postgres Install",
|
||||
"path": "installing/postgres"
|
||||
"title": "KMS",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/kms"
|
||||
},
|
||||
{
|
||||
"title": "AEAD",
|
||||
"path": "configuration/kms/aead"
|
||||
},
|
||||
{
|
||||
"title": "AWS KMS",
|
||||
"path": "configuration/kms/awskms"
|
||||
},
|
||||
{
|
||||
"title": "AliCloud KMS",
|
||||
"path": "configuration/kms/alicloudkms"
|
||||
},
|
||||
{
|
||||
"title": "Azure Key Vault",
|
||||
"path": "configuration/kms/azurekeyvault"
|
||||
},
|
||||
{
|
||||
"title": "GCP Cloud KMS",
|
||||
"path": "configuration/kms/gcpckms"
|
||||
},
|
||||
{
|
||||
"title": "OCI KMS",
|
||||
"path": "configuration/kms/ocikms"
|
||||
},
|
||||
{
|
||||
"title": "Vault Transit",
|
||||
"path": "configuration/kms/transit"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "High Availability Install",
|
||||
"path": "installing/high-availability"
|
||||
"title": "controller",
|
||||
"path": "configuration/controller"
|
||||
},
|
||||
{
|
||||
"title": "Reference Architectures",
|
||||
"path": "installing/reference-architectures"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "API/Clients",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "api-clients"
|
||||
"title": "events",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/events/overview"
|
||||
},
|
||||
{
|
||||
"title": "Common Sink Parameters",
|
||||
"path": "configuration/events/common"
|
||||
},
|
||||
{
|
||||
"title": "File Sink",
|
||||
"path": "configuration/events/file"
|
||||
},
|
||||
{
|
||||
"title": "Stderr Sink",
|
||||
"path": "configuration/events/stderr"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "API",
|
||||
"path": "api-clients/api"
|
||||
},
|
||||
{
|
||||
"title": "CLI",
|
||||
"path": "api-clients/cli"
|
||||
},
|
||||
{
|
||||
"title": "Go SDK",
|
||||
"path": "api-clients/go-sdk"
|
||||
},
|
||||
{
|
||||
"title": "Desktop",
|
||||
"hidden": true,
|
||||
"path": "api-clients/desktop"
|
||||
},
|
||||
{
|
||||
"title": "Desktop",
|
||||
"href": "https://learn.hashicorp.com/tutorials/boundary/getting-started-desktop-app"
|
||||
"title": "plugins",
|
||||
"path": "configuration/plugins"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -242,139 +292,6 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Developing Boundary",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "developing"
|
||||
},
|
||||
{
|
||||
"title": "Building",
|
||||
"path": "developing/building"
|
||||
},
|
||||
{
|
||||
"title": "Developing the UI",
|
||||
"path": "developing/ui"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"divider": true
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration"
|
||||
},
|
||||
{
|
||||
"title": "listener",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/listener"
|
||||
},
|
||||
{
|
||||
"title": "TCP",
|
||||
"path": "configuration/listener/tcp"
|
||||
},
|
||||
{
|
||||
"title": "Unix",
|
||||
"path": "configuration/listener/unix"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "KMS",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/kms"
|
||||
},
|
||||
{
|
||||
"title": "AEAD",
|
||||
"path": "configuration/kms/aead"
|
||||
},
|
||||
{
|
||||
"title": "AWS KMS",
|
||||
"path": "configuration/kms/awskms"
|
||||
},
|
||||
{
|
||||
"title": "AliCloud KMS",
|
||||
"path": "configuration/kms/alicloudkms"
|
||||
},
|
||||
{
|
||||
"title": "Azure Key Vault",
|
||||
"path": "configuration/kms/azurekeyvault"
|
||||
},
|
||||
{
|
||||
"title": "GCP Cloud KMS",
|
||||
"path": "configuration/kms/gcpckms"
|
||||
},
|
||||
{
|
||||
"title": "OCI KMS",
|
||||
"path": "configuration/kms/ocikms"
|
||||
},
|
||||
{
|
||||
"title": "Vault Transit",
|
||||
"path": "configuration/kms/transit"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "controller",
|
||||
"path": "configuration/controller"
|
||||
},
|
||||
{
|
||||
"title": "worker",
|
||||
"path": "configuration/worker"
|
||||
},
|
||||
{
|
||||
"title": "events",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "configuration/events/overview"
|
||||
},
|
||||
{
|
||||
"title": "Common Sink Parameters",
|
||||
"path": "configuration/events/common"
|
||||
},
|
||||
{
|
||||
"title": "File Sink",
|
||||
"path": "configuration/events/file"
|
||||
},
|
||||
{
|
||||
"title": "Stderr Sink",
|
||||
"path": "configuration/events/stderr"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "plugins",
|
||||
"path": "configuration/plugins"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Operations",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "operations"
|
||||
},
|
||||
{
|
||||
"title": "Metrics",
|
||||
"path": "operations/metrics"
|
||||
},
|
||||
{
|
||||
"title": "Health Endpoint",
|
||||
"path": "operations/health"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Common Workflows",
|
||||
"href": "https://learn.hashicorp.com/collections/boundary/basic-administration"
|
||||
@@ -413,12 +330,130 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "API/Clients",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "api-clients"
|
||||
},
|
||||
{
|
||||
"title": "API",
|
||||
"path": "api-clients/api"
|
||||
},
|
||||
{
|
||||
"title": "CLI",
|
||||
"path": "api-clients/cli"
|
||||
},
|
||||
{
|
||||
"title": "Go SDK",
|
||||
"path": "api-clients/go-sdk"
|
||||
},
|
||||
{
|
||||
"title": "Desktop",
|
||||
"hidden": true,
|
||||
"path": "api-clients/desktop"
|
||||
},
|
||||
{
|
||||
"title": "Desktop",
|
||||
"href": "https://learn.hashicorp.com/tutorials/boundary/getting-started-desktop-app"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"divider": true
|
||||
},
|
||||
{
|
||||
"title": "Boundary OSS",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "oss"
|
||||
},
|
||||
{
|
||||
"title": "Installation",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "oss/installing"
|
||||
},
|
||||
{
|
||||
"title": "Dev Mode",
|
||||
"path": "oss/installing/dev-mode"
|
||||
},
|
||||
{
|
||||
"title": "Run and Login",
|
||||
"path": "oss/installing/run-and-login"
|
||||
},
|
||||
{
|
||||
"title": "Connect to Dev Target",
|
||||
"path": "oss/installing/connect-to-dev-target"
|
||||
},
|
||||
{
|
||||
"title": "Non-Dev Environments",
|
||||
"path": "oss/installing/no-gen-resources"
|
||||
},
|
||||
{
|
||||
"title": "Systemd Install",
|
||||
"path": "oss/installing/systemd"
|
||||
},
|
||||
{
|
||||
"title": "Postgres Install",
|
||||
"path": "oss/installing/postgres"
|
||||
},
|
||||
{
|
||||
"title": "High Availability Install",
|
||||
"path": "oss/installing/high-availability"
|
||||
},
|
||||
{
|
||||
"title": "Reference Architectures",
|
||||
"path": "oss/installing/reference-architectures"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Operations",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "oss/operations"
|
||||
},
|
||||
{
|
||||
"title": "Metrics",
|
||||
"path": "oss/operations/metrics"
|
||||
},
|
||||
{
|
||||
"title": "Health Endpoint",
|
||||
"path": "oss/operations/health"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Developing Boundary",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "oss/developing"
|
||||
},
|
||||
{
|
||||
"title": "Building",
|
||||
"path": "oss/developing/building"
|
||||
},
|
||||
{
|
||||
"title": "Developing the UI",
|
||||
"path": "oss/developing/ui"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"divider": true
|
||||
},
|
||||
{
|
||||
"title": "Roadmap",
|
||||
"path": "roadmap"
|
||||
"path": "roadmap",
|
||||
"hidden": true
|
||||
},
|
||||
{
|
||||
"title": "Release Notes",
|
||||
@@ -427,6 +462,10 @@
|
||||
"title": "Overview",
|
||||
"path": "release-notes"
|
||||
},
|
||||
{
|
||||
"title": "v0.9.0",
|
||||
"path": "release-notes/v0_9_0"
|
||||
},
|
||||
{
|
||||
"title": "v0.8.0",
|
||||
"path": "release-notes/v0_8_0"
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
@@ -241,4 +241,32 @@ module.exports = [
|
||||
destination: '/docs/common-workflows/manage-targets#define-a-host',
|
||||
permanent: false,
|
||||
},
|
||||
|
||||
////////////////////////////////////////////
|
||||
// OSS content migration
|
||||
////////////////////////////////////////////
|
||||
|
||||
// below is for moved /installing to /oss/installing
|
||||
|
||||
{
|
||||
source: '/docs/installing/:splat*',
|
||||
destination: '/docs/oss/installing/:splat*',
|
||||
permanent: true,
|
||||
},
|
||||
|
||||
// below is for moved /operations to /oss/operations
|
||||
|
||||
{
|
||||
source: '/docs/operations/:splat*',
|
||||
destination: '/docs/oss/operations/:splat*',
|
||||
permanent: true,
|
||||
},
|
||||
|
||||
// below is for moved /developing to /oss/developing
|
||||
|
||||
{
|
||||
source: '/docs/developing/:splat*',
|
||||
destination: '/docs/oss/developing/:splat*',
|
||||
permanent: true,
|
||||
},
|
||||
]
|
||||
Reference in new issue
Block a user