From 09a1950a6c22e4132031aba1bddf0345bc8affc9 Mon Sep 17 00:00:00 2001 From: Ken Keller Date: Mon, 17 Mar 2025 09:40:29 -0500 Subject: [PATCH] update two pages --- .../hcp/get-started/connect-to-target.mdx | 45 +++++++++--------- .../configure-controllers.mdx | 47 +++++++++---------- 2 files changed, 46 insertions(+), 46 deletions(-) diff --git a/website/content/docs/hcp/get-started/connect-to-target.mdx b/website/content/docs/hcp/get-started/connect-to-target.mdx index fa905474e8..a8917969a1 100644 --- a/website/content/docs/hcp/get-started/connect-to-target.mdx +++ b/website/content/docs/hcp/get-started/connect-to-target.mdx @@ -14,7 +14,7 @@ is the fastest way to onboard a target to HCP Boundary. ![Setup Wizard](/img/setup-wizard-address-target.png) The Quick setup wizard creates a default `tcp` target with the port `22` (the default SSH port using TCP). -The target is created with the address `127.0.0.1`. +The wizard creates the target with the address `127.0.0.1`. When you execute `boundary connect` against this target, Boundary establishes a local, authenticated proxy to the address on the target's default port (`127.0.0.1:22`.) ![Setup Wizard](/img/quick-start-targets.png) @@ -28,44 +28,45 @@ To connect to the initial EC2 Instances target: 1. Open a terminal session. Export the Boundary **Cluster URL** as an environment variable. - ```shell-session - $ export BOUNDARY_ADDR= - ``` + ```shell-session + $ export BOUNDARY_ADDR= + ``` 1. Connect to the target. - ```shell-session - $ boundary connect -target-id ttcp_eTcZMueUYv - ``` + ```shell-session + $ boundary connect -target-id ttcp_eTcZMueUYv + ``` - The output displays the address and port that your SSH client must use. - In the next section the `ssh` connect helper is used to make it easier to connect to the target with a client. + The output displays the address and port that your SSH client must use. + In the next section uses the `ssh` connect helper 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 +For some 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. +The dev-mode default target allows you to make as connections as you want +within the authorized session. When you finish making connections, a +`Ctrl-C/Command-C` to the `boundary connect` process to shut down the session. ## Select 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: +single explicit value. + +Other flags 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 reused -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. +Note however that these are not uniquely identifying, as you may reuse names +across scopes. You must use the target's name in conjunction with the scope name or scope ID +so that Boundary can identify the correct target. Here is an SSH example in dev-mode: @@ -77,7 +78,7 @@ $ boundary connect ssh -target-name "Generated target" -target-scope-name "Gener Boundary includes connect helpers that automatically accept host SSH key prompts for you. -These are written as `boundary connect ` and are supported for the following connection types: +These are `boundary connect ` and support the following connection types: - HTTP - Kubernetes @@ -87,11 +88,11 @@ These are written as `boundary connect ` and are supported for the f Refer to the [Connect helpers](/boundary/docs/concepts/connection-workflows/connect-helpers) documentation for more information. -## Built-in vs. exec +## Built-in verses exec In addition to the built-in connect helpers, `boundary connect` can accommodate executing clients even when there is no built-in support -for a specific client using `-exec`. The `-exec` flag is a very powerful +for a specific client using `-exec`. The `-exec` flag is a 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. @@ -130,6 +131,6 @@ Refer to the [Connect to your First Target](/boundary/tutorials/hcp-getting-star ## Next steps -Refer to our [basic administration +Refer to the [basic administration workflows](/boundary/tutorials/hcp-administration) tutorial series for in depth discussions on managing scopes, targets, identities, and sessions. \ No newline at end of file diff --git a/website/content/docs/install-boundary/configure-controllers.mdx b/website/content/docs/install-boundary/configure-controllers.mdx index afc4af1711..f6b8b14e52 100644 --- a/website/content/docs/install-boundary/configure-controllers.mdx +++ b/website/content/docs/install-boundary/configure-controllers.mdx @@ -7,12 +7,12 @@ description: >- # Configure controllers -Refer to the sections below to configure your Boundary controllers. +Refer to the later sections to configure your Boundary controllers. ## Prepare TLS certificates HashiCorp recommends that the Boundary controller nodes handle TLS via PKI for user connections. -Further, we strongly recommend that you use certificates that are generated and signed by an appropriate certificate authority (CA). +Further, HashiCorp strongly recommend that you use certificates generated and signed by an appropriate certificate authority (CA). To use TLS, you must have two files on each Boundary controller node. You may have to create a new directory to store the certificate material at `/etc/boundary.d/tls`. @@ -20,7 +20,7 @@ Place the files in the following paths: - `/etc/boundary.d/tls/boundary-cert.pem` - In this path, place the Boundary TLS certificate with a Common Name (CN) and Subject Alternate Name (SAN) that matches your planned primary DNS record for accessing the Boundary controllers and any additional SANs as necessary. + This path is for accessing the Boundary controllers and any SANs. Place the Boundary TLS certificate with a Common Name (CN) and Subject Alternate Name (SAN) that matches your planned primary DNS record in this path. - `/etc/boundary.d/tls/boundary-key.pem` In this path, place the Boundary TLS certificate's private key. @@ -32,19 +32,19 @@ If you do not generate unique TLS key material for each node, you should securel Boundary controllers require the two following different cryptographic keys: - **Root key**: The root KMS key acts as a KEK (Key Encrypting Key) for the scope-specific KEKs (also referred to as the scope's root key). -The scope's root KEK and the various DEKs (Data Encryption Keys) are created when a scope is created. -The DEKs are encrypted with the scope's root KEK, and this is in turn encrypted with the KMS key marked for the root purpose. -- **Recovery key**: The recovery KMS key is used for rescue or recovery operations that can be used by a client to authenticate almost any Boundary operation. -A nonce and creation time are included as an encrypted payload, formatted as a token, and sent to the controller. -The time and nonce are used to ensure that a value cannot be replayed by an adversary, and also to ensure that each operation must be individually authenticated by a client, so that revoking access to the KMS has an immediate result. +At the creation time of a scope, the root KEK and the various DEKs (Data Encryption Keys) are also created. +Using the scope's KEL, it encrypts the DEKs, and this is in turn encrypted with the KMS key marked for the root purpose. +- **Recovery key**: The recovery KMS key is for rescue or recovery operations, and can authenticate almost any Boundary operation. +An encrypted payload includes a nonce and creation time, formatted as a token, and sent to the controller. +The time and nonce ensure that an adversary cannot replay a value, and also to ensure that each operation must be individually authenticated by a client, so that revoking access to the KMS has an immediate result. The following keys are optional: -- **Worker-auth key (Optional)**: The worker-auth KMS key is shared by the controller and worker to authenticate a worker to the controller. -If a worker is used with PKI authentication, this is unnecessary. -- **BSR key (Optional)**: The BSR KMS key is required for session recording. +- **Worker-auth key (Optional)**: The controller and worker share the worker-auth KMS key to authenticate a worker to the controller. +If a worker uses PKI authentication, this is unnecessary. +- **BSR key (Optional)**: Session recording requires the BSR KMS key. Boundary uses the BSR key for encrypting data and checking the integrity of recordings. -If you do not add a BSR key to your controller configuration, you receive an error when you attempt to enable session recording. +If you do not add a BSR key to your controller configuration, you receive an error when you try to enable session recording. There are other optional KMS keys that you can configure for different encryption scenarios. These scenarios include Boundary worker PKI auth encryption and Boundary worker or controller configuration encryption. @@ -52,7 +52,7 @@ Refer to [Data security in Boundary](/boundary/docs/concepts/security/data-encry There are two types of Boundary workers, distinguished by the method by which they authenticate with the Boundary controllers. -One worker uses a PKI exchange to authenticate with the controllers, and the other uses a KMS key that can be used for authentication by both the worker and the controller. +One worker uses a PKI exchange to authenticate with the controllers. The other uses a KMS key used for authentication by both the worker and the controller. You use the Worker-auth key listed above to enable KMS worker authentication. @@ -95,12 +95,12 @@ Run the following commands to rename the example configuration files: 1. `sudo mv controller.hcl controller.hcl.old` 1. `sudo mv worker.hcl worker.hcl.old` -We recommend that you use either the `env://` or `file://` notation in the configuration files to securely provide secret configuration components to the Boundary controller binaries. -In the following controller configuration example, we use `env://` to declare the PostgreSQL connection string, as well as secure the AWS KMS configuration items. +HashiCorp recommends that you use either the `env://` or `file://` notation in the configuration files to securely provide secret configuration components to the Boundary controller binaries. +In the following controller configuration example, declare the PostgreSQL connect strings with `env://` as well as secure the AWS KMS configuration items. When you install the Boundary binary using a package manager, it includes a unit file that configures an environment file at `/etc/boundary.d/boundary.env`. -You can use this file to set the sensitive values that are used to configure the Boundary controllers and workers. -The following is an example of how this environment file could be configured: +You can use this file to set the sensitive values used to configure the Boundary controllers and workers. +The following is an example of a configuration using this environment file: @@ -262,10 +262,10 @@ kms "awskms" { Refer to the list below for explanations of the parameters used in the example above: -- `disable mlock (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory from being swapped to the disk. +- `disable mlock (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory swap to the disk. This is fine for local development and testing. -However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. -Boundary only supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD. +However, it is not recommended for production unless the systems running Boundary use encrypted swap or do not use swap at all. +Boundary supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD. On Linux, to give the Boundary executable the ability to use `mlock` syscall without running the process as root, run the following command: @@ -299,14 +299,13 @@ Refer to the documentation for additional [top-level configuration options](/bou ## Initialize the database Before you can start Boundary, you must initialize the database from one Boundary controller. -This operation is only required once; it will execute the required database migrations for the Boundary cluster to operate. +Initialisation must run once; it will execute the required database migrations for the Boundary cluster to operate. ```shell-session boundary database init -config /etc/boundary.d/controller.hcl ``` -Boundary automatically generates a number of resources to make getting started easier. Default scopes, auth methods, -user, account, and targets are some of the resources Boundary automatically generates unless you configure it not to. These +Unless you configure it not to, Boundary automatically generates a number of resources to make getting started easier. It automatically generates default scopes, auth methods, user, account, and targets. These resources, however, are not required. You can add the following flags to skip creating these initial resources: ```shell-session @@ -318,7 +317,7 @@ boundary database init \ -config /etc/boundary.d/controller.hcl ``` -Use the following command to view the help for additional options: +Use the following command to view the help for options: ```shell-session boundary database init -h