CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: IA reorganization (#5838)

Browse Source 
* docs: IA reorganization

* docs: Updates

* docs: Updates

* docs: Fix links

* docs: Updates

* docs: Fix a typo

* docs: Fix client agent topic

* docs: Update Client Agent nav

* docs: Fix conflict

* docs: Fix a typo in Client Agent docs (#5853)

* docs: Fix client agent topic

* docs: Updates

* docs: Updates

* docs: Updates

* docs: Updates

* docs: Fixes get started and operations links

* docs: Update nav

* docs: Partials

* docs: Unix partials

* docs: Worker partials

* docs: Updates

* docs: Update workers and targets

* docs: Updates

* docs: Updates

* docs: Fixes link

* docs: Updates after sync review

* docs: Updates from review feedback

* docs: Move worker filter examples

* docs: Fix links

* docs: Updates for filters based on working session

* docs: Fixes broken links

* docs: Add links to other filter topics

* docs: Update list intro

* docs: Adds link

* docs: Fixes redirects

* docs: Fixes redirects

* docs: Deleted mysql page from TOC

* docs: Add versioned redirect

* docs: Adds versioned redirects

* docs: Adds versioned redirects

* docs: Update redirects

* docs: Update redirects

* docs: Redirect fixes

* docs: Update redirect format

* docs: Fix a typo

* docs: Fixes redirects

* docs: Fixes redirect

* docs: Adds links out to client agent troubleshooting

* uses /etc/boundary.d/ as recommended installation directory (#6003)

* docs: Updates legacy io links

* docs: Fixes redirects

* docs: Fix redirect

* docs: Restoring deleted file

---------

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
This commit is contained in:
Dan HeathandRobin Beck authored and GitHub committed 2025-09-03 15:45:38 -04:00
1 parent 21fce7c5eb
commit 5ce6515156
253 files changed
+7897 -5673
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CHANGELOG.md
+12 -12
View File
@@ -7,8 +7,8 @@ Canonical reference for changes, improvements, and bugfixes for Boundary.
### New and Improved
* cli: Added `boundary connect mysql` command for connecting to MySQL targets.
This new helper command allows users to authorize sessions against MySQL
targets and automatically invoke a MySQL client with the appropriate
This new helper command allows users to authorize sessions against MySQL
targets and automatically invoke a MySQL client with the appropriate
connection parameters and credentials.
* Adds support to parse User-Agent headers and emit them in telemetry events
([PR](https://github.com/hashicorp/boundary/pull/5645)).
@@ -20,7 +20,7 @@ Canonical reference for changes, improvements, and bugfixes for Boundary.
### Deprecations/Changes
* Modified parsing logic for various IP/host/address fields across Boundary.
Notably, for some fields, Boundary previously required bracket-enclosed
Notably, for some fields, Boundary previously required bracket-enclosed
IPv6 addresses (eg: `[::1]`). With this change, if the provided address is
just an IPv6 literal, enclosing the address in brackets is not valid.
Additionally, an input address containing an IPv6 literal may be modified by
@@ -998,7 +998,7 @@ open-source release of 0.12.3; the same fixes will be in 0.13.0 OSS.
Encryption Keys (KEKs) and Data Encryption Keys (DEKs) using the new key rotation
and key version destruction functionality. To learn more about this new feature,
refer to the
[documentation](https://developer.hashicorp.com/boundary/docs/concepts/security/data-encryption).
[documentation](https://developer.hashicorp.com/boundary/docs/secure/encryption/data-encryption).
Upgrade notice: If the Database purpose DEK for a scope is destroyed, you must use
the API to cancel any sessions that predate the upgrade.
@@ -1408,7 +1408,7 @@ open-source release of 0.12.3; the same fixes will be in 0.13.0 OSS.
anonymous user; currently these are the same permissions as assigned in
Boundary's default role permissions. If other use-cases arise this list can be
expanded. See [the
documentation](https://www.boundaryproject.io/docs/concepts/security/permissions/assignable-permissions)
documentation](https://www.developer.hashicorp.com/boundary/docs/rbac/assignable-permissions)
for more details.
## 0.8.1 (2022/05/13)
@@ -1567,7 +1567,7 @@ isolate transactions and prevent resource contention that caused deadlocks.
* Boundary now supports dynamic discovery of host resources using our (currently
internal) new plugin system. See the
[documentation](https://www.boundaryproject.io/docs) for configuration
[documentation](https://www.developer.hashicorp.com/boundary/docs) for configuration
instructions. Currently, only Azure and AWS are supported, but more providers
will be following in future releases.
* workers: The existing worker connection replay prevention logic has been
@@ -1696,7 +1696,7 @@ isolate transactions and prevent resource contention that caused deadlocks.
* OIDC Accounts: When performing a `read` on an `oidc` type account, the
original token and userinfo claims are provided in the output. This can make
it significantly easier to write filters to create [managed
groups](https://www.boundaryproject.io/docs/concepts/filtering/oidc-managed-groups).
groups](https://www.developer.hashicorp.com/boundary/docs/rbac/users/managed-groups).
([PR](https://github.com/hashicorp/boundary/pull/1419))
* Controllers will now mark connections as closed in the database if the worker
has not reported its status; this can be seen as the controller counterpart to
@@ -1724,7 +1724,7 @@ isolate transactions and prevent resource contention that caused deadlocks.
Boundary.
* Filtering events: hclog log levels have been replaced by optional sets
of allow and deny event
[filters](https://www.boundaryproject.io/docs/concepts/filtering) which are
[filters](https://www.developer.hashicorp.com/boundary/docs/filtering) which are
specified via configuration, or in the case of "boundary dev" there are new
new cmd flags.
* Observation events are MVP and contain a minimal set of observations about a
@@ -1937,7 +1937,7 @@ Boundary) but it's worth repeating.
users this defaults to all fields; for `u_anon` this defaults to the fields
useful for navigating to and authenticating to the system. In either case,
this is overridable. See the [permissions
documentation](https://www.boundaryproject.io/docs/concepts/security/permissions)
documentation](https://www.developer.hashicorp.com/boundary/docs/rbac)
for more information on why and when to use this. This currently only applies
to top-level fields in the response.
* cli/api/sdk: Add support to request additional OIDC claims scope values from
@@ -2123,7 +2123,7 @@ to call out in this changelog. The full set of open issues is on GitHub.
* list filtering: Listing now supports filtering results before being returned
to the user. The filtering takes place server side and uses boolean
expressions against the JSON representation of returned items. See [the
documentation](https://www.boundaryproject.io/docs/concepts/filtering/resource-listing)
documentation](https://www.developer.hashicorp.com/boundary/docs/filtering)
for more details. ([PR 1](https://github.com/hashicorp/boundary/pull/952))
([PR 2](https://github.com/hashicorp/boundary/pull/957))
([PR 3](https://github.com/hashicorp/boundary/pull/967))
@@ -2131,7 +2131,7 @@ to call out in this changelog. The full set of open issues is on GitHub.
worked before but wasn't fully tested.)
([PR](https://github.com/hashicorp/boundary/pull/959))
* server: On `SIGHUP`, [worker
tags](https://www.boundaryproject.io/docs/configuration/worker#tags) will be
tags](https://www.developer.hashicorp.com/boundary/docs/workers/worker-tags) will be
re-parsed and new values used
([PR](https://github.com/hashicorp/boundary/pull/959))
* server: In addition to the existing `tls_min_version` listener configuration
@@ -2368,7 +2368,7 @@ them to access targets).
favor of specifying `none` for the new `-keyring-type` parameter.
* [`pass`](https://www.passwordstore.org/) is now the default keyring type on
non-Windows/non-macOS platforms. See the [CLI docs
page](https://www.boundaryproject.io/docs/api-clients/cli) for more
page](https://www.developer.hashicorp.com/boundary/docs/commands) for more
information.
### New and Improved
README.md
+17 -17
View File
@@ -1,9 +1,9 @@
# Boundary
- What is Boundary: https://developer.hashicorp.com/boundary/docs/overview/what-is-boundary
- Website: https://www.boundaryproject.io/
- What is Boundary: https://developer.hashicorp.com/boundary/docs/what-is-boundary
- Website: https://www.developer.hashicorp.com/boundary/
- Forums: [HashiCorp Discuss](https://discuss.hashicorp.com/c/boundary/)
- Documentation: [https://boundaryproject.io/docs](https://boundaryproject.io/docs)
- Documentation: [https://developer.hashicorp.com/boundary/docs](https://developer.hashicorp.com/boundary/docs)
- Tutorials: [HashiCorp's Learn Platform](https://developer.hashicorp.com/boundary/tutorials)
<img alt="Boundary" src="boundary.png" alt="Image" width="500px"/>
@@ -13,25 +13,26 @@ Boundary is an identity-aware proxy that provides a simple, secure way to access
With Boundary you can:
* Integrate with your IdP of choice using OpenID Connect, enabling users to securely sign-in to their Boundary environment
* Provide just-in-time network access to network resources, wherever they reside
* Provide just-in-time network access to network resources, wherever they reside
* Manage session credentials via a native static credential store, or dynamically generate unique per-session credentials by integrating with HashiCorp Vault
* Automate discovery of new endpoints
* Manage privileged sessions using Boundary’s session controls
* Standardize your team's access workflow with a consistent experience for any type of infrastructure across any provider
Boundary is designed to be straightforward to understand, highly scalable, and
Boundary is designed to be straightforward to understand, highly scalable, and
resilient. It can run in clouds, on-prem, secure enclaves and more, and does not require
an agent to be installed on every end host, making it suitable for access to managed/cloud services and container-based workflows in addition to traditional host systems and services.
<video controls>
<source src="https://www.datocms-assets.com/2885/1694719896-how-boundary-works-v3.mp4" type="video/mp4" alt="Watch the video" />
</video>
<img src="https://www.boundaryproject.io/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F58478%2F1664218843-boundary-illustration-option2-1.png&w=3840&q=75" alt="Watch the video" width="320" height="180">
For more information, refer to "[What is Boundary?](https://developer.hashicorp.com/boundary/docs/overview/what-is-boundary)" on the Boundary website.
For more information, refer to "[What is Boundary?](https://developer.hashicorp.com/boundary/docs/what-is-boundary)" on the Boundary website.
## Getting Started
Boundary consists of two server components:
Boundary consists of two server components:
* **Controller**, which serves the API and coordinate session requests
* **Workers**, which perform session handling
@@ -40,7 +41,7 @@ A real-world Boundary installation will likely consist of one or more
controllers paired with one or more workers. A single Boundary binary can act
in either, or both, of these two modes.
Additionally, Boundary provides a Desktop client and CLI for end-users to request and establish
Additionally, Boundary provides a Desktop client and CLI for end-users to request and establish
authorized sessions to resources across a network.
<img src="boundary_desktop_example.gif" alt="Boundary Desktop GIF" width="66%" height="66%" loop="true">
@@ -49,29 +50,29 @@ Boundary does _not_ require software to be installed on your hosts and services.
## Requirements
Boundary has two external dependencies:
Boundary has two external dependencies:
- A SQL database
- At least one KMS
### SQL database
The database contains Boundary's configuration and session information. The
controller nodes must be able to access the database.
The database contains Boundary's configuration and session information. The
controller nodes must be able to access the database.
Values that are secrets (e.g credentials) are encrypted in the database. Currently, PostgreSQL is supported as a database and has been tested with Postgres 12 and above.
Boundary uses only common extensions and both hosted and self-managed instances are supported. In most instances, all that you need is a database endpoint and the appropriate credentials.
### KMS
### KMS
Boundary uses KMS keys for various purposes, such as protecting secrets, authenticating workers, recovering data, encrypting values in Boundary’s configuration, and more. Boundary uses key derivation extensively to avoid key sprawl of these high-value keys.
You can use [any cloud KMS or Vault's Transit Secrets Engine to satisfy the KMS requirement](https://developer.hashicorp.com/boundary/docs/configuration/kms).
You can use [any cloud KMS or Vault's Transit Secrets Engine to satisfy the KMS requirement](https://developer.hashicorp.com/boundary/docs/configuration/kms).
## Trying out Boundary
Running Boundary in a more permanent context requires a few more steps, such
as writing some simple configuration files to tell the nodes how to reach their
database and KMS. The steps below, along with the extra information needed
for permanent installations, are detailed in our [Installation Guide](https://developer.hashicorp.com/boundary/docs/install-boundary/install).
for permanent installations, are detailed in our [Installation Guide](https://developer.hashicorp.com/boundary/docs/deploy/self-managed/install).
> ⚠️ Do _not_ use the `main` branch except for dev or test cases. Boundary 0.10 introduced release branches which should be safe to track, however, migrations in `main` may be renumbered if needed. The Boundary team will not be able to provide assistance if running `main` over the long term results in migration breakages or other bugs.
@@ -193,4 +194,3 @@ _please responsibly disclose_ by contacting us at
Thank you for your interest in contributing! Please refer to
[CONTRIBUTING.md](https://github.com/hashicorp/boundary/blob/main/CONTRIBUTING.md) for guidance.
website/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Boundary Documentation Website
This subdirectory contains the content for the [Boundary Website](https://boundaryproject.io/).
This subdirectory contains the content for the [Boundary Website](https://developer.hashicorp.com/boundary/).
<!--
This readme file contains several blocks of generated text, to make it easier to share common information
website/content/docs/api-clients/client-agent.mdx
-785
View File
@@ -1,785 +0,0 @@
---
layout: docs
page_title: Client Agent overview
description: >-
Learn how the Boundary Client Agent intercepts DNS requests as the primary resolver on the system, allowing Boundary to proxy connections transparently.
---
# Boundary Client Agent
@include 'alerts/enterprise-only.mdx'
The Boundary Client Agent is Boundary's DNS daemon.
When the Boundary Client Agent runs alongside an authenticated Boundary client, the agent establishes itself as the primary resolver on the system and intercepts DNS requests.
If you enter a hostname that matches a Boundary alias that the client is authorized to establish a session to, Boundary automatically generates the session and transparently proxies the connection on your behalf.
If the Boundary Client Agent cannot find an alias, or if there are any issues with authentication, network connectivity, or latency, the Client Agent defers DNS resolution to the previously configured DNS resolvers.
<Note>
You must enable both IPv4 and IPv6 protocols for your environment to ensure the Client Agent can start and perform DNS lookups.
</Note>
## Security
When you successfully authorize a session on a Boundary controller, the response includes a list of any brokered credentials, which include the decoded secrets.
When the Boundary Client Agent receives a DNS request, Boundary creates a new session.
An OS user can only connect to an authorized session managed by the Boundary Client Agent daemon if they are the same OS user that added the Boundary auth token used for authorizing the session.
<Note>
Currently, you cannot authenticate to multiple Boundary controllers at once.
If you authenticate to a different Boundary controller, any existing sessions are terminated and any new transparent sessions would be established with the new controller.
</Note>
The Boundary Client Agent stores the credentials and some other information related to the session in memory.
The in-memory store removes the session information:
- when the session ends.
- if the auth token stored in the Boundary expires.
- if the current OS user authenticates with a different Boundary user.
- if the current OS user authenticates to a new Boundary controller.
- if the Boundary Client Agent is paused.
- if the Boundary Client Agent is terminated.
API requests are authenticated in the same way as session proxy access.
Credential brokering is supported for transparent sessions.
A notification appears when you establish a session against a target that is configured with credential brokering.
You can retrieve the credentials later using the following command:
```shell-session
$ boundary client-agent sessions
```
### Grants
In a production environment, you may want to provide the least amount of privileges necessary for users.
For a Boundary user to be able to use the Client Agent to establish a transparent session, they must:
- be able to authenticate using an auth method.
- have read permissions for their auth token.
- have permission to establish a session to one or more targets.
You can use the following grant strings to grant those permissions:
```
type=auth-method;ids=*;actions=authorize
type=target;ids=*;actions=authorize-session
type=auth-token;ids=*;actions=read:self
```
HashiCorp highly recommends that you also grant users the permission to list resolvable aliases, as the Client Agent periodically fetches a list of aliases to match incoming DNS requests against.
Without that permission, every DNS request on the system is sent to the Boundary controller, which can easily overwhelm it.
You can use the following grant string to grant the permission to list resolvable aliases:
```
type=user;ids=*;actions=list-resolvable-aliases
```
<Warning>
A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases.
Clusters created before April 26, 2025 may be missing the following grants:
`ids={{.User.Id}};type=user;actions=list-resolvable-aliases`
`ids=*;type=target;actions=list,read`
If your cluster is missing these grants, HashiCorp recommends adding them.
For more information, refer to the [known issue](/boundary/docs/release-notes/v0_19_0#hcp-grants).
</Warning>
## Configuration
The default configuration included with the Boundary Client Agent upon installation will be suitable for most users. If you want to make changes to the configuration, the configuration file is located in the following directory:
<Tabs>
<Tab heading="MacOS" group="macos">
`/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl`
</Tab>
<Tab heading="Windows" group="windows">
`C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl`
</Tab>
</Tabs>
The configuration file contains the following fields:
- `alias_refresh_interval` - Specifies how often to refresh the alias cache. The default value is 1 minute.
Example:
```hcl
alias_refresh_interval="60s"
```
- `dns_request_timeout` - Specifies for how long the Client Agent DNS request handling, including any recursion, is allowed to run before it is canceled.
Example:
```hcl
dns_request_timeout="300s"
```
- `interface_to_use` - Specifies the interface to use instead of the default.
Example:
```hcl
interface_to_use="en1"
```
- `log_file` - Specifies where to write the Boundary Client Agent log file to.
Example:
```hcl
log_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent.log"
```
- `log_level` - Specifies the verbosity of the Client Agent logs.
Example:
```hcl
log_level="DEBUG"
```
- `log_to_stdout` - Logs to STDOUT in addition to the `boundary-client-agent.log` file.
Example:
```hcl
log_to_stdout=false
```
- `override_upstream_dns_servers` - Lists the DNS servers that should be used for recursing non-Boundary requests, overriding those configured on the system.
Example:
```hcl
override_upstream_dns_servers = ["8.8.8.8", "8.8.4.4"]
```
- `state_file` - Specifies where to write the Boundary Client Agent state file to. This is an ephemeral file which is removed on successful shutdown.
Example:
```hcl
state_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent-state.json"
```
- `v4_prefix` - Specifies an alternate prefix to use for generating IPs. Currently must be between /8 and /16
Example:
```hcl
v4_prefix=1.1.1.1/8
```
### Change the configuration
Complete the following steps to change the configuration of the Client Agent:
<Tabs>
<Tab heading="MacOS" group="macos">
1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice.
By default, it is located in the following directory:
`/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl`
1. Change the configuration settings, and save the file.
<Note>
You must restart the Client Agent to update some configuration settings.
However, when you restart the Client Agent, it closes any existing sessions.
Other configuration settings can be updated by only reloading the configuration file, which does not affect any existing sessions.
</Note>
1. Either reload the configuration file or restart the Client Agent.
You can change the following configuration values by reloading the configuration file, which will not disrupt any existing sessions:
- `dns_request_timeout`
- `log_file`
- `log_level`
- `state_file`
- `override_upstream_dns_servers`
- `v4_prefix`
Run the following command to reload the configuration file:
```shell-session
$ sudo pkill -1 boundary-client-agent
```
If you want to update another configuration value, you can restart the Client Agent using the following commands, however it will close any existing sessions:
```shell-session
$ sudo launchctl stop com.hashicorp.boundary.boundary-client-agent
$ sudo launchctl start com.hashicorp.boundary.boundary-client-agent
```
</Tab>
<Tab heading="Windows" group="windows">
1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice.
By default, it is located in the following directory:
`C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl`
1. Change the configuration settings, and save the file.
1. Run the following commands to restart the Client Agent.
```shell-session
net stop BoundaryClientAgent
net start BoundaryClientAgent
```
Note that when you restart the Client Agent, it closes any existing sessions.
</Tab>
</Tabs>
## Manage the Client Agent
Refer to the following sections for more information about managing the Client Agent.
You can monitor the Client Agent's status and retrieve information about any transparent sessions.
If you want to temporarily defer DNS resolution to any previously configured DNS resolvers, you can pause the Client Agent.
You can also disable the Client Agent, if you no longer want to use it for DNS resolution.
### Monitor status and sessions
You can check the status of the Client Agent to ensure it is running.
Use the following command to check the Client Agent's status:
```shell-session
$ boundary client-agent status
```
You can retrieve information about the sessions that the Client Agent is managing.
Use the following command to list any sessions currently being managed by the Client Agent, as well as any brokered credentials for those sessions:
```shell-session
$ boundary client-agent sessions
```
Note that this command does not list sessions that are not managed by the Client Agent. Use `boundary sessions list -recursive` to see all sessions.
### Pause the Client Agent
You can temporarily disable the Boundary Client Agent by pausing it with the following command:
```shell-session
$ boundary client-agent pause
```
When the Client Agent is paused, it does not intercept any DNS requests, and you are unable to use transparent sessions.
To resume the Client Agent, use the following command:
```shell-session
$ boundary client-agent resume
```
### Disable the Client Agent
If you want to disable the Boundary Client Agent, you can stop it with the following commands:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo launchctl unload -w /Library/LaunchDaemons/com.hashicorp.boundary.boundary-client-agent.plist
```
Unloading the Boundary Client Agent removes its launch daemon configuration. To restart the Client Agent, use:
```shell-session
$ sudo launchctl load -w /Library/LaunchDaemons/com.hashicorp.boundary.boundary-client-agent.plist
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
net stop BoundaryClientAgent
```
</Tab>
</Tabs>
## Troubleshooting
The following sections can help you to troubleshoot the Client Agent's behavior. You should proceed through these steps from top to bottom.
### Check the status of the Client Agent
If you experience unexpected behavior, you should first check on the status of the Client Agent.
You can check the status using the Boundary CLI or the Desktop Client. To check the Client Agent status through the Boundary CLI, use the following command:
```shell-session
$ boundary client-agent status
Status:
Address:
https://boundary.corp.com
Auth Token Expiration: 167h58m9s
Auth Token Id: at_GBqZUK2ihv
Status: running
Version: 0.0.1-e561e69839cce148ee5045684bce5b7168c65026
```
In the Desktop Client, you can find the status of the Client Agent by navigating to **Settings**, and then scrolling to the **Boundary Client Agent** section.
The status command includes various information about the Client Agent, including the runtime status.
In this example, the runtime status is "running".
If the status is "paused", the Client Agent is not currently intercepting DNS requests and must be resumed.
Users can pause the Client Agent, and it will also pause itself if it detects a large number of network failures in a short period of time.
The status also allows you to see whether the current user is authenticated.
If the response looks like the example above, including showing an auth token ID and expiration, your current user is authenticated.
If not, you may need to first authenticate to the Client Agent using the CLI or Desktop Client.
The status also sometimes contains a list of errors that have been encountered by the Client Agent.
The list is ordered by most recent first.
These errors can help you understand why the Client Agent may not be behaving as expected.
Please see the section below on common error messages to help diagnose specific errors.
Note that this list of errors will not be cleared until the next reboot, so it may not necessarily be a sign of something being wrong.
If the status command returns an error, the Client Agent may not be running.
You can attempt to start the Client Agent using the following commands:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo launchctl start com.hashicorp.boundary.boundary-client-agent
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
net start BoundaryClientAgent
```
</Tab>
</Tabs>
### Resume the Client Agent
You can resume the Client Agent using either the Boundary CLI or the Desktop Client. In the CLI, run the following command to resume the Client Agent:
```shell-session
$ boundary client-agent resume
The Client Agent has been successfully resumed.
```
In the Desktop Client, you can resume the Client Agent by selecting the **Resume** button in the **Boundary Client Agent** section of the settings.
Once the Client Agent has resumed, test if it has started working as expected again.
### Inspect the log file
If you are not able to diagnose the problem by looking at the status or resuming the Client Agent, another step can be to inspect the log file produced by the Client Agent.
<Tabs>
<Tab heading="MacOS" group="macos">
The log file should be located in `/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.log`.
</Tab>
<Tab heading="Windows" group="windows">
The log file should be located in `C:\Windows\Logs\boundary-client-agent.log`.
</Tab>
</Tabs>
Once you have found the log file, you can look through it to see if you can understand why the Client Agent is not working as expected.
The list below provides some common errors and explanations.
It may be necessary to increase the logging verbosity of the Client Agent.
You can increase the verbosity by setting the `log_level` option in the configuration file to `"DEBUG"`.
See the section on changing the configuration for more information.
### Establish the behavior of the local DNS configuration
The Client Agent works by intercepting DNS requests before they are sent to your regular DNS server.
If the DNS requests on your system are not sent to the right place, or they are not being answered appropriately, transparent sessions will not work.
You can use the `nslookup` command to understand where the DNS requests are being sent.
Start by sending a DNS request for `hashicorp.com`:
```shell-session
$ nslookup hashicorp.com
;; Truncated, retrying in TCP mode.
Server: 100.88.241.86
Address: 100.88.241.86#53
Non-authoritative answer:
Name: hashicorp.com
Address: 76.76.21.21
```
The important part here is the `Server` field, which contains an IP in the CGNAT range (from `100.64.0.0` to `100.127.255.255`).
This is a good indication that the Client Agent DNS server is being used as expected.
Next, you can try to make a DNS request to an alias that you expect to work. The following example makes a DNS request to an alias with a value of `mytarget.boundary.dev`:
```shell-session
$ nslookup mytarget.boundary.dev
;; Truncated, retrying in TCP mode.
Server: fc00:a20a::d7bf:c059
Address: fc00:a20a::d7bf:c059#53
Name: mytarget.boundary.dev
Address: 100.84.164.9
```
You can tell two things from this:
1. The Client Agent is likely able to intercept the DNS request, because the server is a local IPv6 address in the [ULA](https://en.wikipedia.org/wiki/Unique_local_address) range.
Both an IPv4 CGNAT range or IPv6 ULA range IP address are indications of this.
2. The Client Agent is able to identify `mytarget.boundary.dev` as an alias with a target that the requesting user is authorized to connect to, because it responded with a valid DNS response pointing to a local IPv4 address in the CGNAT range.
Similarly to above, the IP address in the response may also be an IPv6 address in the ULA range.
If you do not see this kind of response, it may be that the alias you are trying to connect to doesn't exist, or your user is not authorized to connect to it.
Double check that you are using the correct alias and that your user is authorized to connect to it.
### Flush OS DNS cache
If you still do not see the expected behavior, it can be useful to flush the operating system's DNS cache.
The exact steps depend on the operating system you use:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
ipconfig /flushdns
```
</Tab>
</Tabs>
After you flush the DNS cache, try connecting to the alias again, or repeat the steps above.
If you are still not able to understand what is wrong, submit a support ticket. Include the `boundary client-agent status` output and the log file in the ticket.
### Common error messages
Refer to the following common error messages for more information about their possible causes and resolutions.
#### nodename nor servname provided, or not known / No such host is known
This is a generic error for a failed DNS resolution.
It can mean a number of different things:
- The alias doesn't exist or is misspelled.
- Your user isn't authenticated or doesn't have permission to connect to the target.
- The Client Agent is not able to intercept DNS requests, it could shut down or paused.
- The OS DNS cache is interfering with the operation of the Client Agent.
- The Client Agent may not yet know about the alias.
It takes around 2 minutes for the Client Agent to learn about new aliases.
Follow the troubleshooting steps above to resolve the issue.
#### failed to listen for DNS on either IPv4 or IPv6
This error happens when some other application on the local machine occupies the ports used by the Boundary Client Agent.
The Client Agent requires access to port 53 for IPv4 and IPv6, both UDP and TCP.
Diagnosing what causes the error differs per operating system:
<Tabs>
<Tab heading="MacOS" group="macos">
As a privileged user, you can use the `lsof` program to find what applications are occupying a port, for example:
```shell-session
$ sudo lsof -nP | grep ":53"
```
If anything is occupying port 53, you may need to terminate the application before the Client Agent is able to start.
Applications that make use of the Apple Virtualization Framework are known to sometimes occupy this port under
the name `_mdnsresponder`. If you have any virtualization software, you may need to turn it off before using
the Client Agent.
</Tab>
<Tab heading="Windows" group="windows">
As a privileged user, you can open the **Resource Monitor** and inspect the **Network** > **Listening Ports** section to find any applications that use port 53.
</Tab>
</Tabs>
Once you have identified which other software is using the port, you can stop it and try to start the Client Agent again.
#### failed to refresh alias cache: error="fetching resolvable aliases: error performing client request during List call"
This usually implies that there is a problem reaching the internet or the Boundary controller.
The error is related to the periodic updating of aliases used by the Client Agent to know whether a DNS request matches an alias or not.
HashiCorp recommends that you pause the Client Agent and examine the status and logs for further errors:
```shell-session
$ boundary client-agent pause
```
Follow the troubleshooting steps to understand why the Client Agent is not able to reach the controller.
#### sendmsg: broken pipe
On MacOS versions 15.1 and 15.2, the firewall may incorrectly block the Client Agent from sending DNS responses. To resolve this issue,
upgrade to MacOS version 15.3 or later.
It may be neccessary to explicitly allow the `boundary-client-agent` process access to incoming network connections.
From the Firewall options in System Settings, toggle the `boundary-client-agent` to **Allow incoming connections**.
#### WARNING! Remote host indentification has changed! It is possible that someone is doing something nasty!
This error arises when you use an alias to connect to an SSH target after the first successful connection using that alias. The issue occurs because Boundary workers generate a new host key on every new SSH connection. You can safely ignore the warning using the `StrictHostKeyChecking=no` command line option:
```shell-session
$ ssh -o StrictHostKeyChecking=no targetalias.boundary.dev
```
You can also remove the existing server host key from the `~/.ssh/known_hosts` file to avoid the error.
#### This site can't be reached... DNS_PROBE_FINISHED_NXDOMAIN
This error occurs when you have authenticated to Boundary and have a target that is configured with an alias.
When you copy the alias from the **Target** page and paste it in the browser, you receive the error.
The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."
A conflicting service may be preventing the Client Agent from receiving DNS requests.
The service may be bound to port 53.
Restarting your computer may resolve the conflict.
#### error when attempting to resume... bind address already in use: invalid state transition
This error occurs when you have authenticated to Boundary and have a target that is configured with an alias.
When you attempt to use the alias to connect to the target, you receive the error message in Boundary Desktop.
The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."
A conflicting service may be preventing the Client Agent from receiving DNS requests.
The service may be bound to port 53.
Restarting your computer may resolve the conflict.
## Conflicting software
Some software is known to cause conflicts with the Boundary Client Agent.
Refer to the [transparent sessions interoperability matrix](/boundary/docs/configuration/target-aliases/interoperability-matrix) for a list of the third-party products that have been tested for use with the Boundary Client Agent.
The following sections are an incomplete list of potential conflicts and any available workarounds for issues.
### Cloudflare WARP client
The Cloudflare WARP client uses a local DNS server to direct traffic.
It has built-in checks to prevent it from being run alongside other software that uses the same mechanism.
This includes the Boundary Client Agent.
If you try to use the Client Agent with the Cloudflare WARP client, it may work, or you may see an error like this one:
```
Status: Unable to Connect
Error reason: DNS Proxy Failure
Error code: CF_DNS_PROXY_FAILURE
Error description: The WARP Agent must be the only process responsible for DNS resolution on the device. One or more processes are already bound to port 53: boundary-client-agent.
Learn more: https://cfl.re/CF_DNS_PROXY_FAILURE
```
You can still install both the Cloudflare WARP client and the Boundary Client Agent on the same machine.
The two products can coexist as long as the WARP client starts first.
Starting the WARP client first binds it to alternate IPs and leaves the domain available for Boundary.
### Docker Desktop (MacOS)
Docker Desktop sometimes creates a local DNS listener that prevents the Client Agent from running.
If you run Docker Desktop 4.26 or later, you must clear the `Use kernel networking for UDP` option.
Otherwise, the Client Agent refuses to start.
### Huntress EDR client (Windows)
Host isolation and release do not work as expected in Windows when you use the Huntress EDR client with the Boundary Client Agent.
The Huntress EDR client for Windows uses the Windows Filtering Platform (WFP) to isolate devices by blocking all non-essential traffic. This behavior conflicts with the Boundary Client Agent during device isolation.
Specifically, the Boundary Client Agent replaces the default DNS resolver with its own, which can prevent fallback to a secondary DNS when the primary (Boundary) DNS fails during isolation.
As a result, Huntress is unable to maintain server communication, leaving the device stuck in an isolated state. Huntress cannot isolate and release devices properly in Windows under these conditions.
As a temporary workaround, you can manually configure a secondary DNS (e.g., 8.8.8.8). However, this secondary DNS setting is overwritten when you pause or resume the Boundary Client Agent, so you must configure it again each time.
This issue does not affect macOS devices, where Boundary and Huntress coexist without additional configuration.
### Internet Sharing (MacOS)
Enabling **Internet Sharing** on MacOS causes the system's DNS resolver (`mDNSResponder`) to bind to all interfaces on port 53, preventing the Client Agent from starting. Disable **Internet Sharing** before you run the Client Agent.
### OpenVPN
When you run OpenVPN at the same time as the Client Agent, it can create a DNS conflict.
If you are unable to establish a transparent session while using OpenVPN, you may need to explicitly specify a network interface and upstream DNS server(s) to use.
To configure the DNS server(s) to use, use the `override_upstream_dns_servers` configuration option:
```hcl
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
```
<Note>
The `override_upstream_dns_servers` is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
</Note>
If you configured OpenVPN to push DNS servers to the client, it may create additional conflicts.
Refer to the sections below for more information about how this configuration affects MacOS and Windows systems.
#### MacOS
When OpenVPN is configured to push DNS servers to the client, the client-side service monitors and updates the system DNS settings.
As a result, OpenVPN may attempt to override the Client Agent's configuration.
This scenario can create an unstable network environment and lead to disruptions in user connectivity and service access.
There is no workaround for this scenario at this time.
#### Windows
When OpenVPN is configured to push DNS servers to the client, it creates `DNSClientNrptRule` entries in Windows that control DNS routing independently of the interface priority.
Although the Client Agent updates the interface's DNS settings, it does not manage the Name Resolution Policy Table (NRPT).
As a result, the OpenVPN rules may override the Client Agent's configuration.
This scenario may lead to conflicts, and there is no supported workaround at this time.
### Palo Alto Networking Global Protect VPN
If you are unable to establish a transparent session while using the Palo Alto Networking Global Protect VPN, you may need to explicitly specify a network interface and the upstream DNS server(s) to use.
By default, the Client Agent reads the primary network interface's DNS server configuration and uses that information to resolve domains that are not configured as aliases in Boundary.
If the VPN configuration includes custom DNS servers, this information may not be available to the Client Agent, so you must explicitly specify the DNS server(s) to use.
To configure the DNS server(s) to use, use the `override_upstream_dns_servers` configuration option:
```hcl
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
```
<Note>
The `override_upstream_dns_servers` is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
</Note>
#### Primary network interfaces
By default, the Client Agent creates IPs on the primary network interface to serve its DNS server.
Refer to the tabs below for possible conflicts for each supported operating system.
<Tabs>
<Tab heading="MacOS" group="macos">
When you run the Client Agent alongside the PAN-GP VPN, the primary network interface will likely be set to a `tun` type interface, which the Client Agent cannot use for its IP addresses.
You may see errors such as the following in the `boundary-client-agent.log` file or the `boundary client-agent status` command response:
```
[ERROR] macos.addIP: error adding ipv4 address: ifconfig: ioctl (SIOCAIFADDR): Destination address required
```
To work around the default `tun` interface, you must provide an explicit network interface using the `interface_to_use` configuration option. For example:
```hcl
interface_to_use=en0
```
The `interface_to_use` option allows the Client Agent to create the IPs it needs to serve the DNS server and proxy traffic.
You must restart the Client Agent for it to update its configuration with the new setting.
</Tab>
<Tab heading="Windows" group="windows">
On Windows, the Client Agent may be able to create the IPs that it needs on the primary network interface, but it fails to establish any transparent sessions. You may see the following message:
```
[INFO] default route change detected, restarting
```
You must explicitly specify a network interface to use other than the primary one. You can list available network interfaces using the Powershell command `Get-NetAdapter`, or the older `route print` command. You must find the index of the interface you would normally use to connect to the internet. In this example, the interface index is `11`:
```
PS C:\> Get-NetAdapter
Name InterfaceDescription ifIndex Status MacAddress LinkSpeed
---- -------------------- ------- ------ ---------- ---------
Ethernet Parallels VirtIO Ethernet Adapter 11 Up 00-1C-42-B3-F2-75 10 Gbps
Ethernet 2 PANGP Virtual Ethernet Adapter Secure 24 Up 02-50-41-00-00-01 2 Gbps
```
Alternatively, if you use `route print`, refer to the following example:
```
PS C:\> route print
===========================================================================
Interface List
24...02 50 41 00 00 01 ......PANGP Virtual Ethernet Adapter Secure
11...00 1c 42 b3 f2 75 ......Parallels VirtIO Ethernet Adapter
1...........................Software Loopback Interface 1
===========================================================================
````
Your configuration should look like this:
```hcl
interface_to_use=11
```
You must restart the Client Agent for it to update its configuration with the new setting.
</Tab>
</Tabs>
### Parallels Desktop (MacOS VM on MacOS Host)
Running a MacOS VM in Parallels Desktop with shared networking causes the system's DNS resolver (`mDNSResponder`) to bind to all interfaces, blocking port 53 and preventing the Client Agent from starting.
As a workaround, you can configure Parallels Desktop to use a different network mode.
Select an alternative network configuration such as **Host-Only**, **Default Adapter**, or **Wi-Fi** instead of **Shared Network**.
Refer to the Parallels Desktop documentation for more information.
## Uninstall the Client Agent on Mac
If you used the Mac installer, you can run `/Library/Application Support/HashiCorp/Boundary Uninstaller.app` to uninstall Boundary.
The uninstaller removes any installed components, including the Desktop client, CLI, and the Boundary Client Agent.
## More information
Refer to the following topics for more information:
- [Aliases](/boundary/docs/concepts/aliases)
- [Transparent sessions](/boundary/docs/concepts/transparent-sessions)
website/content/docs/api-clients/api/index.mdx → website/content/docs/api/index.mdx
+5 -5
View File
@@ -5,11 +5,11 @@ description: >-
Learn about Boundary's HTTP API standards, status codes, path layout, methods, and headers. Understand how rate limiting helps manage system resources.
---
# API
# Boundary API overview
Boundary's API is a JSON-based HTTP API that adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output.
Before reading this page, it is useful to understand Boundary's [domain model](/boundary/docs/concepts/domain-model) to be aware of the terminology used here.
Before reading this page, it is useful to understand Boundary's [domain model](/boundary/docs/domain-model) to be aware of the terminology used here.
Boundary's API is also described via OpenAPI v2; the version corresponding to any tag of Boundary's source code can be found in Boundary's [GitHub repository](https://github.com/hashicorp/boundary/blob/main/internal/gen/controller.swagger.json).
@@ -19,7 +19,7 @@ Boundary's current API version is 1; all API paths begin with `/v1/`.
## Status codes
- `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes. (Starting with Boundary 0.2.1, `delete` actions return `204` on success.)
- `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes. Any `delete` actions return `204` on success.
- `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below.
- `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action.
- `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action.
@@ -99,8 +99,8 @@ If you do not provide an `X-Correlation-ID` header, Boundary generates a unique
If your controllers try to process every API request, they may either run out of resources or overwhelm the database server.
Boundary features API rate limiting to help prevent system resources from being overwhlemed by too many simultaneous requests.
For more information, refer to [API rate limiting](/boundary/docs/api-clients/api/rate-limiting).
For more information, refer to [API rate limiting](/boundary/docs/api/rate-limiting).
When you search for Boundary resources using the `list` operation, you could potentially receive a very large number of results.
Boundary uses an API pagination feature to enable you to search and filter large lists of search results without overwhelming your system resources.
Refer to [API list pagination](/boundary/docs/api-clients/api/pagination) for more information about pagination and using the local cache for searches.
Refer to [API list pagination](/boundary/docs/api/pagination) for more information about pagination and using the local cache for searches.
website/content/docs/api-clients/api/pagination.mdx → website/content/docs/api/pagination.mdx
View File
File renamed without changes.
website/content/docs/api-clients/api/rate-limiting.mdx → website/content/docs/api/rate-limiting.mdx
+1 -1
View File
@@ -50,7 +50,7 @@ Each response contains the `RateLimit` and `RateLimit-Policy` headers.
If the request is rate limited, Boundary sends the client a 429 HTTP status code with a `Retry-After` header.
The `Retry-After` header contains the number of seconds the client should wait before it sends the request again.
For more information, refer to [HTTP headers](/boundary/docs/api-clients/api#http-headers).
For more information, refer to [HTTP headers](/boundary/docs/api#http-headers).
## More information
website/content/docs/install-boundary/architecture/fault-tolerance.mdx → website/content/docs/architecture/fault-tolerance.mdx
View File
File renamed without changes.
website/content/docs/install-boundary/architecture/high-availability.mdx → website/content/docs/architecture/high-availability.mdx
+2 -2
View File
@@ -35,7 +35,7 @@ Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS](
### Database
Boundary controllers must be able to reach the PostgreSQL database.
If you use a [high availability](/boundary/docs/install-boundary/high-availability) (HA) configuration, then the controllers must have access to the PostgreSQL server infrastructure.
If you use a high availability (HA) configuration, then the controllers must have access to the PostgreSQL server infrastructure.
For more information about configuring the Postgres database for HA, refer to the [Postgres high availability, load balancing, and replication documentation](https://www.postgresql.org/docs/current/high-availability.html).
If you use a managed service, refer to your provider's PostgreSQL high availability documentation.
@@ -51,6 +51,6 @@ For general configuration, we recommend the following:
### Controller configuration
When running Boundary controller as a service we recommend storing the file at `/etc/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it.
When running Boundary controller as a service we recommend storing the file at `/etc/boundary.d/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it.
For detailed configuration options, see our [configuration docs](/boundary/docs/configuration).
website/content/docs/install-boundary/architecture/recommended-architecture.mdx → website/content/docs/architecture/recommended-architecture.mdx
View File
File renamed without changes.
website/content/docs/install-boundary/architecture/system-requirements.mdx → website/content/docs/architecture/system-requirements.mdx
+3 -3
View File
@@ -24,7 +24,7 @@ To match your requirements and maximize the stability of your Boundary
controller and worker instances, perform load tests and monitor
resource usage including reported matrices from Boundary's telemetry.
Refer to [Maintaining and operating Boundary](/boundary/docs/operations) for
Refer to [Monitor Boundary](/boundary/docs/monitor) for
more information.
## Hardware sizing for Boundary servers
@@ -105,7 +105,7 @@ If you restrict network egress, ensure you allow outgoing access from:
If any of the default port mappings do not meet your organization's
requirements, you can update the default listening ports using the resource's
[listener](/boundary/docs/configuration/listener) stanza.
[listener](/boundary/docs/monitor/listeners) stanza.
</Note>
@@ -226,4 +226,4 @@ There are also a number of self-hosted options, as well as service discovery
systems like Consul.
Refer to the [listener stanza
documentation](/boundary/docs/configuration/listener/) for more information.
documentation](/boundary/docs/monitor/listeners/) for more information.
website/content/docs/client-agent/configuration.mdx
+159
View File
@@ -0,0 +1,159 @@
---
layout: docs
page_title: Configure the Client Agent
description: >-
Learn how to configure the Boundary Client Agent to intercept DNS requests, allowing Boundary to proxy connections transparently.
---
# Configure the Client Agent
@include 'alerts/enterprise-only.mdx'
The default configuration included with the Boundary Client Agent upon installation will be suitable for most users. If you want to make changes to the configuration, the configuration file is located in the following directory:
<Tabs>
<Tab heading="MacOS" group="macos">
`/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl`
</Tab>
<Tab heading="Windows" group="windows">
`C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl`
</Tab>
</Tabs>
## Configuration settings
The configuration file contains the following fields:
- `alias_refresh_interval` - Specifies how often to refresh the alias cache. The default value is 1 minute.
Example:
```hcl
alias_refresh_interval="60s"
```
- `dns_request_timeout` - Specifies for how long the Client Agent DNS request handling, including any recursion, is allowed to run before it is canceled.
Example:
```hcl
dns_request_timeout="300s"
```
- `interface_to_use` - Specifies the interface to use instead of the default.
Example:
```hcl
interface_to_use="en1"
```
- `log_file` - Specifies where to write the Boundary Client Agent log file to.
Example:
```hcl
log_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent.log"
```
- `log_level` - Specifies the verbosity of the Client Agent logs.
Example:
```hcl
log_level="DEBUG"
```
- `log_to_stdout` - Logs to STDOUT in addition to the `boundary-client-agent.log` file.
Example:
```hcl
log_to_stdout=false
```
- `override_upstream_dns_servers` - Lists the DNS servers that should be used for recursing non-Boundary requests, overriding those configured on the system.
Example:
```hcl
override_upstream_dns_servers = ["8.8.8.8", "8.8.4.4"]
```
- `state_file` - Specifies where to write the Boundary Client Agent state file to. This is an ephemeral file which is removed on successful shutdown.
Example:
```hcl
state_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent-state.json"
```
- `v4_prefix` - Specifies an alternate prefix to use for generating IPs. Currently must be between /8 and /16
Example:
```hcl
v4_prefix=1.1.1.1/8
```
## Change the configuration
Complete the following steps to change the configuration of the Client Agent:
<Tabs>
<Tab heading="MacOS" group="macos">
1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice.
By default, it is located in the following directory:
`/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl`
1. Change the configuration settings, and save the file.
<Note>
You must restart the Client Agent to update some configuration settings.
However, when you restart the Client Agent, it closes any existing sessions.
Other configuration settings can be updated by only reloading the configuration file, which does not affect any existing sessions.
</Note>
1. Either reload the configuration file or restart the Client Agent.
You can change the following configuration values by reloading the configuration file, which will not disrupt any existing sessions:
- `dns_request_timeout`
- `log_file`
- `log_level`
- `state_file`
- `override_upstream_dns_servers`
- `v4_prefix`
Run the following command to reload the configuration file:
```shell-session
$ sudo pkill -1 boundary-client-agent
```
If you want to update another configuration value, you can restart the Client Agent using the following commands, however it will close any existing sessions:
```shell-session
$ sudo launchctl stop com.hashicorp.boundary.boundary-client-agent
$ sudo launchctl start com.hashicorp.boundary.boundary-client-agent
```
</Tab>
<Tab heading="Windows" group="windows">
1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice.
By default, it is located in the following directory:
`C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl`
1. Change the configuration settings, and save the file.
1. Run the following commands to restart the Client Agent.
```shell-session
net stop BoundaryClientAgent
net start BoundaryClientAgent
```
Note that when you restart the Client Agent, it closes any existing sessions.
</Tab>
</Tabs>
website/content/docs/client-agent/conflicting-software.mdx
+209
View File
@@ -0,0 +1,209 @@
---
layout: docs
page_title: Client Agent conflicting software
description: >-
Learn how possible conflicts that third-party tools may have with the Boundary Client Agent. Explore possible solutions and workarounds.
---
# Client Agent software conflicts
Some software is known to cause conflicts with the Boundary Client Agent.
Refer to the [transparent sessions interoperability matrix](/boundary/docs/interoperability-matrix) for a list of the third-party products that have been tested for use with the Boundary Client Agent.
The following sections are an incomplete list of potential conflicts and any available workarounds for issues.
## Cloudflare WARP client
The Cloudflare WARP client uses a local DNS server to direct traffic.
It has built-in checks to prevent it from being run alongside other software that uses the same mechanism.
This includes the Boundary Client Agent.
If you try to use the Client Agent with the Cloudflare WARP client, it may work, or you may see an error like this one:
```
Status: Unable to Connect
Error reason: DNS Proxy Failure
Error code: CF_DNS_PROXY_FAILURE
Error description: The WARP Agent must be the only process responsible for DNS resolution on the device. One or more processes are already bound to port 53: boundary-client-agent.
Learn more: https://cfl.re/CF_DNS_PROXY_FAILURE
```
You can still install both the Cloudflare WARP client and the Boundary Client Agent on the same machine.
The two products can coexist as long as the WARP client starts first.
Starting the WARP client first binds it to alternate IPs and leaves the domain available for Boundary.
## Docker Desktop (MacOS)
Docker Desktop sometimes creates a local DNS listener that prevents the Client Agent from running.
If you run Docker Desktop 4.26 or later, you must clear the `Use kernel networking for UDP` option.
Otherwise, the Client Agent refuses to start.
## Huntress EDR client (Windows)
Host isolation and release do not work as expected in Windows when you use the Huntress EDR client with the Boundary Client Agent.
The Huntress EDR client for Windows uses the Windows Filtering Platform (WFP) to isolate devices by blocking all non-essential traffic. This behavior conflicts with the Boundary Client Agent during device isolation.
Specifically, the Boundary Client Agent replaces the default DNS resolver with its own, which can prevent fallback to a secondary DNS when the primary (Boundary) DNS fails during isolation.
As a result, Huntress is unable to maintain server communication, leaving the device stuck in an isolated state. Huntress cannot isolate and release devices properly in Windows under these conditions.
As a temporary workaround, you can manually configure a secondary DNS (e.g., 8.8.8.8). However, this secondary DNS setting is overwritten when you pause or resume the Boundary Client Agent, so you must configure it again each time.
This issue does not affect macOS devices, where Boundary and Huntress coexist without additional configuration.
## Internet Sharing (MacOS)
Enabling **Internet Sharing** on MacOS causes the system's DNS resolver (`mDNSResponder`) to bind to all interfaces on port 53, preventing the Client Agent from starting. Disable **Internet Sharing** before you run the Client Agent.
## OpenVPN
When you run OpenVPN at the same time as the Client Agent, it can create a DNS conflict.
If you are unable to establish a transparent session while using OpenVPN, you may need to explicitly specify a network interface and upstream DNS server(s) to use.
To configure the DNS server(s) to use, use the `override_upstream_dns_servers` configuration option:
```hcl
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
```
<Note>
The `override_upstream_dns_servers` is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
</Note>
If you configured OpenVPN to push DNS servers to the client, it may create additional conflicts.
Refer to the sections below for more information about how this configuration affects MacOS and Windows systems.
### MacOS
When OpenVPN is configured to push DNS servers to the client, the client-side service monitors and updates the system DNS settings.
As a result, OpenVPN may attempt to override the Client Agent's configuration.
This scenario can create an unstable network environment and lead to disruptions in user connectivity and service access.
There is no workaround for this scenario at this time.
### Windows
When OpenVPN is configured to push DNS servers to the client, it creates `DNSClientNrptRule` entries in Windows that control DNS routing independently of the interface priority.
Although the Client Agent updates the interface's DNS settings, it does not manage the Name Resolution Policy Table (NRPT).
As a result, the OpenVPN rules may override the Client Agent's configuration.
This scenario may lead to conflicts, and there is no supported workaround at this time.
## Palo Alto Networking Global Protect VPN
If you are unable to establish a transparent session while using the Palo Alto Networking Global Protect VPN, you may need to explicitly specify a network interface and the upstream DNS server(s) to use.
By default, the Client Agent reads the primary network interface's DNS server configuration and uses that information to resolve domains that are not configured as aliases in Boundary.
If the VPN configuration includes custom DNS servers, this information may not be available to the Client Agent, so you must explicitly specify the DNS server(s) to use.
To configure the DNS server(s) to use, use the `override_upstream_dns_servers` configuration option:
```hcl
# The DNS servers must be specified as an IP, or an IP:Port.
# If no port is provided, port 53 is assumed.
# The order of the entries specifies the priority.
# We recommended providing both the VPN DNS servers
# and the default DNS servers, so that DNS requests can
# be resolved even when the VPN is not active.
override_upstream_dns_servers = [
"10.0.0.1", # Example primary VPN DNS server
"10.0.0.2", # Example secondary VPN DNS server
"8.8.8.8", # Fallback default DNS server
"8.8.4.4:53", # Fallback default DNS server with a custom port
]
```
<Note>
The `override_upstream_dns_servers` is used for all non-Boundary DNS requests.
If you only provide the VPN DNS servers, the Client Agent will not be able to resolve any DNS requests when the VPN is not active.
</Note>
### Primary network interfaces
By default, the Client Agent creates IPs on the primary network interface to serve its DNS server.
Refer to the tabs below for possible conflicts for each supported operating system.
<Tabs>
<Tab heading="MacOS" group="macos">
When you run the Client Agent alongside the PAN-GP VPN, the primary network interface will likely be set to a `tun` type interface, which the Client Agent cannot use for its IP addresses.
You may see errors such as the following in the `boundary-client-agent.log` file or the `boundary client-agent status` command response:
```
[ERROR] macos.addIP: error adding ipv4 address: ifconfig: ioctl (SIOCAIFADDR): Destination address required
```
To work around the default `tun` interface, you must provide an explicit network interface using the `interface_to_use` configuration option. For example:
```hcl
interface_to_use=en0
```
The `interface_to_use` option allows the Client Agent to create the IPs it needs to serve the DNS server and proxy traffic.
You must restart the Client Agent for it to update its configuration with the new setting.
</Tab>
<Tab heading="Windows" group="windows">
On Windows, the Client Agent may be able to create the IPs that it needs on the primary network interface, but it fails to establish any transparent sessions. You may see the following message:
```
[INFO] default route change detected, restarting
```
You must explicitly specify a network interface to use other than the primary one. You can list available network interfaces using the Powershell command `Get-NetAdapter`, or the older `route print` command. You must find the index of the interface you would normally use to connect to the internet. In this example, the interface index is `11`:
```
PS C:\> Get-NetAdapter
Name InterfaceDescription ifIndex Status MacAddress LinkSpeed
---- -------------------- ------- ------ ---------- ---------
Ethernet Parallels VirtIO Ethernet Adapter 11 Up 00-1C-42-B3-F2-75 10 Gbps
Ethernet 2 PANGP Virtual Ethernet Adapter Secure 24 Up 02-50-41-00-00-01 2 Gbps
```
Alternatively, if you use `route print`, refer to the following example:
```
PS C:\> route print
===========================================================================
Interface List
24...02 50 41 00 00 01 ......PANGP Virtual Ethernet Adapter Secure
11...00 1c 42 b3 f2 75 ......Parallels VirtIO Ethernet Adapter
1...........................Software Loopback Interface 1
===========================================================================
````
Your configuration should look like this:
```hcl
interface_to_use=11
```
You must restart the Client Agent for it to update its configuration with the new setting.
</Tab>
</Tabs>
## Parallels Desktop (MacOS VM on MacOS Host)
Running a MacOS VM in Parallels Desktop with shared networking causes the system's DNS resolver (`mDNSResponder`) to bind to all interfaces, blocking port 53 and preventing the Client Agent from starting.
As a workaround, you can configure Parallels Desktop to use a different network mode.
Select an alternative network configuration such as **Host-Only**, **Default Adapter**, or **Wi-Fi** instead of **Shared Network**.
Refer to the Parallels Desktop documentation for more information.
## Uninstall the Client Agent on Mac
If you used the Mac installer, you can run `/Library/Application Support/HashiCorp/Boundary Uninstaller.app` to uninstall Boundary.
The uninstaller removes any installed components, including the Desktop client, CLI, and the Boundary Client Agent.
website/content/docs/client-agent/index.mdx
+113
View File
@@ -0,0 +1,113 @@
---
layout: docs
page_title: Client Agent overview
description: >-
Learn how the Boundary Client Agent intercepts DNS requests as the primary resolver on the system, allowing Boundary to proxy connections transparently.
---
# Boundary Client Agent
@include 'alerts/enterprise-only.mdx'
The Boundary Client Agent is Boundary's DNS daemon.
When the Boundary Client Agent runs alongside an authenticated Boundary client, the agent establishes itself as the primary resolver on the system and intercepts DNS requests.
If you enter a hostname that matches a Boundary alias that the client is authorized to establish a session to, Boundary automatically generates the session and transparently proxies the connection on your behalf.
If the Boundary Client Agent cannot find an alias, or if there are any issues with authentication, network connectivity, or latency, the Client Agent defers DNS resolution to the previously configured DNS resolvers.
<Note>
You must enable both IPv4 and IPv6 protocols for your environment to ensure the Client Agent can start and perform DNS lookups.
</Note>
## Security
When you successfully authorize a session on a Boundary controller, the response includes a list of any brokered credentials, which include the decoded secrets.
When the Boundary Client Agent receives a DNS request, Boundary creates a new session.
An OS user can only connect to an authorized session managed by the Boundary Client Agent daemon if they are the same OS user that added the Boundary auth token used for authorizing the session.
<Note>
Currently, you cannot authenticate to multiple Boundary controllers at once.
If you authenticate to a different Boundary controller, any existing sessions are terminated and any new transparent sessions would be established with the new controller.
</Note>
The Boundary Client Agent stores the credentials and some other information related to the session in memory.
The in-memory store removes the session information:
- when the session ends.
- if the auth token stored in the Boundary expires.
- if the current OS user authenticates with a different Boundary user.
- if the current OS user authenticates to a new Boundary controller.
- if the Boundary Client Agent is paused.
- if the Boundary Client Agent is terminated.
API requests are authenticated in the same way as session proxy access.
Credential brokering is supported for transparent sessions.
A notification appears when you establish a session against a target that is configured with credential brokering.
You can retrieve the credentials later using the following command:
```shell-session
$ boundary client-agent sessions
```
### Grants
In a production environment, you may want to provide the least amount of privileges necessary for users.
For a Boundary user to be able to use the Client Agent to establish a transparent session, they must:
- be able to authenticate using an auth method.
- have read permissions for their auth token.
- have permission to establish a session to one or more targets.
You can use the following grant strings to grant those permissions:
```
type=auth-method;ids=*;actions=authorize
type=target;ids=*;actions=authorize-session
type=auth-token;ids=*;actions=read:self
```
HashiCorp highly recommends that you also grant users the permission to list resolvable aliases, as the Client Agent periodically fetches a list of aliases to match incoming DNS requests against.
Without that permission, every DNS request on the system is sent to the Boundary controller, which can easily overwhelm it.
You can use the following grant string to grant the permission to list resolvable aliases:
```
type=user;ids=*;actions=list-resolvable-aliases
```
<Warning>
A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases.
Clusters created before April 26, 2025 may be missing the following grants:
`ids={{.User.Id}};type=user;actions=list-resolvable-aliases`
`ids=*;type=target;actions=list,read`
If your cluster is missing these grants, HashiCorp recommends adding them.
For more information, refer to the [known issue](/boundary/docs/release-notes/v0_19_0#hcp-grants).
</Warning>
## More information
Refer to the following topics for more information:
- [Aliases](/boundary/docs/concepts/aliases)
- [Transparent sessions](/boundary/docs/concepts/transparent-sessions)
## Next steps
Refer to the following topics for more information about installing, configuring, and using the Client Agent:
- [Install Boundary clients](/boundary/docs/deploy/self-managed/install-clients)
- [Configure the Client Agent](/boundary/docs/client-agent/configuration)
- [Manage the Client Agent](/boundary/docs/client-agent/manage)
- [Troubleshoot issues with the Client Agent](/boundary/docs/client-agent/troubleshoot)
- [Client Agent software conflicts](/boundary/docs/client-agent/conflicting-software)
website/content/docs/client-agent/manage.mdx
+74
View File
@@ -0,0 +1,74 @@
---
layout: docs
page_title: Manage the Client Agent
description: >-
Learn how to manage the Boundary Client Agent to intercept DNS requests, allowing Boundary to proxy connections transparently.
---
# Manage the Client Agent
Refer to the following sections for more information about managing the Client Agent.
You can monitor the Client Agent's status and retrieve information about any transparent sessions.
If you want to temporarily defer DNS resolution to any previously configured DNS resolvers, you can pause the Client Agent.
You can also disable the Client Agent, if you no longer want to use it for DNS resolution.
## Monitor status and sessions
You can check the status of the Client Agent to ensure it is running.
Use the following command to check the Client Agent's status:
```shell-session
$ boundary client-agent status
```
You can retrieve information about the sessions that the Client Agent is managing.
Use the following command to list any sessions currently being managed by the Client Agent, as well as any brokered credentials for those sessions:
```shell-session
$ boundary client-agent sessions
```
Note that this command does not list sessions that are not managed by the Client Agent. Use `boundary sessions list -recursive` to see all sessions.
## Pause the Client Agent
You can temporarily disable the Boundary Client Agent by pausing it with the following command:
```shell-session
$ boundary client-agent pause
```
When the Client Agent is paused, it does not intercept any DNS requests, and you are unable to use transparent sessions.
To resume the Client Agent, use the following command:
```shell-session
$ boundary client-agent resume
```
## Disable the Client Agent
If you want to disable the Boundary Client Agent, you can stop it with the following commands:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo launchctl unload -w /Library/LaunchDaemons/com.hashicorp.boundary.boundary-client-agent.plist
```
Unloading the Boundary Client Agent removes its launch daemon configuration. To restart the Client Agent, use:
```shell-session
$ sudo launchctl load -w /Library/LaunchDaemons/com.hashicorp.boundary.boundary-client-agent.plist
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
net stop BoundaryClientAgent
```
</Tab>
</Tabs>
website/content/docs/client-agent/troubleshoot.mdx
+283
View File
@@ -0,0 +1,283 @@
---
layout: docs
page_title: Troubleshoot the Client Agent
description: >-
Troubleshoot issues with the Boundary Client Agent to ensure it is functioning properly.
---
# Troubleshoot issues with the Client Agent
The following sections can help you to troubleshoot the Client Agent's behavior. You should proceed through these steps from top to bottom.
## Check the status of the Client Agent
If you experience unexpected behavior, you should first check on the status of the Client Agent.
You can check the status using the Boundary CLI or the Desktop Client. To check the Client Agent status through the Boundary CLI, use the following command:
```shell-session
$ boundary client-agent status
Status:
Address:
https://boundary.corp.com
Auth Token Expiration: 167h58m9s
Auth Token Id: at_GBqZUK2ihv
Status: running
Version: 0.0.1-e561e69839cce148ee5045684bce5b7168c65026
```
In the Desktop Client, you can find the status of the Client Agent by navigating to **Settings**, and then scrolling to the **Boundary Client Agent** section.
The status command includes various information about the Client Agent, including the runtime status.
In this example, the runtime status is "running".
If the status is "paused", the Client Agent is not currently intercepting DNS requests and must be resumed.
Users can pause the Client Agent, and it will also pause itself if it detects a large number of network failures in a short period of time.
The status also allows you to see whether the current user is authenticated.
If the response looks like the example above, including showing an auth token ID and expiration, your current user is authenticated.
If not, you may need to first authenticate to the Client Agent using the CLI or Desktop Client.
The status also sometimes contains a list of errors that have been encountered by the Client Agent.
The list is ordered by most recent first.
These errors can help you understand why the Client Agent may not be behaving as expected.
Please see the section below on common error messages to help diagnose specific errors.
Note that this list of errors will not be cleared until the next reboot, so it may not necessarily be a sign of something being wrong.
If the status command returns an error, the Client Agent may not be running.
You can attempt to start the Client Agent using the following commands:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo launchctl start com.hashicorp.boundary.boundary-client-agent
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
net start BoundaryClientAgent
```
</Tab>
</Tabs>
## Resume the Client Agent
You can resume the Client Agent using either the Boundary CLI or the Desktop Client. In the CLI, run the following command to resume the Client Agent:
```shell-session
$ boundary client-agent resume
The Client Agent has been successfully resumed.
```
In the Desktop Client, you can resume the Client Agent by selecting the **Resume** button in the **Boundary Client Agent** section of the settings.
Once the Client Agent has resumed, test if it has started working as expected again.
## Inspect the log file
If you are not able to diagnose the problem by looking at the status or resuming the Client Agent, another step can be to inspect the log file produced by the Client Agent.
<Tabs>
<Tab heading="MacOS" group="macos">
The log file should be located in `/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.log`.
</Tab>
<Tab heading="Windows" group="windows">
The log file should be located in `C:\Windows\Logs\boundary-client-agent.log`.
</Tab>
</Tabs>
Once you have found the log file, you can look through it to see if you can understand why the Client Agent is not working as expected.
The list below provides some common errors and explanations.
It may be necessary to increase the logging verbosity of the Client Agent.
You can increase the verbosity by setting the `log_level` option in the configuration file to `"DEBUG"`.
See the section on changing the configuration for more information.
## Establish the behavior of the local DNS configuration
The Client Agent works by intercepting DNS requests before they are sent to your regular DNS server.
If the DNS requests on your system are not sent to the right place, or they are not being answered appropriately, transparent sessions will not work.
You can use the `nslookup` command to understand where the DNS requests are being sent.
Start by sending a DNS request for `hashicorp.com`:
```shell-session
$ nslookup hashicorp.com
;; Truncated, retrying in TCP mode.
Server: 100.88.241.86
Address: 100.88.241.86#53
Non-authoritative answer:
Name: hashicorp.com
Address: 76.76.21.21
```
The important part here is the `Server` field, which contains an IP in the CGNAT range (from `100.64.0.0` to `100.127.255.255`).
This is a good indication that the Client Agent DNS server is being used as expected.
Next, you can try to make a DNS request to an alias that you expect to work. The following example makes a DNS request to an alias with a value of `mytarget.boundary.dev`:
```shell-session
$ nslookup mytarget.boundary.dev
;; Truncated, retrying in TCP mode.
Server: fc00:a20a::d7bf:c059
Address: fc00:a20a::d7bf:c059#53
Name: mytarget.boundary.dev
Address: 100.84.164.9
```
You can tell two things from this:
1. The Client Agent is likely able to intercept the DNS request, because the server is a local IPv6 address in the [ULA](https://en.wikipedia.org/wiki/Unique_local_address) range.
Both an IPv4 CGNAT range or IPv6 ULA range IP address are indications of this.
2. The Client Agent is able to identify `mytarget.boundary.dev` as an alias with a target that the requesting user is authorized to connect to, because it responded with a valid DNS response pointing to a local IPv4 address in the CGNAT range.
Similarly to above, the IP address in the response may also be an IPv6 address in the ULA range.
If you do not see this kind of response, it may be that the alias you are trying to connect to doesn't exist, or your user is not authorized to connect to it.
Double check that you are using the correct alias and that your user is authorized to connect to it.
## Flush OS DNS cache
If you still do not see the expected behavior, it can be useful to flush the operating system's DNS cache.
The exact steps depend on the operating system you use:
<Tabs>
<Tab heading="MacOS" group="macos">
```shell-session
$ sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
```
</Tab>
<Tab heading="Windows" group="windows">
```shell-session
ipconfig /flushdns
```
</Tab>
</Tabs>
After you flush the DNS cache, try connecting to the alias again, or repeat the steps above.
If you are still not able to understand what is wrong, submit a support ticket. Include the `boundary client-agent status` output and the log file in the ticket.
## Common error messages
Refer to the following common error messages for more information about their possible causes and resolutions.
### nodename nor servname provided, or not known / No such host is known
This is a generic error for a failed DNS resolution.
It can mean a number of different things:
- The alias doesn't exist or is misspelled.
- Your user isn't authenticated or doesn't have permission to connect to the target.
- The Client Agent is not able to intercept DNS requests, it could shut down or paused.
- The OS DNS cache is interfering with the operation of the Client Agent.
- The Client Agent may not yet know about the alias.
It takes around 2 minutes for the Client Agent to learn about new aliases.
Follow the troubleshooting steps above to resolve the issue.
### failed to listen for DNS on either IPv4 or IPv6
This error happens when some other application on the local machine occupies the ports used by the Boundary Client Agent.
The Client Agent requires access to port 53 for IPv4 and IPv6, both UDP and TCP.
Diagnosing what causes the error differs per operating system:
<Tabs>
<Tab heading="MacOS" group="macos">
As a privileged user, you can use the `lsof` program to find what applications are occupying a port, for example:
```shell-session
$ sudo lsof -nP | grep ":53"
```
If anything is occupying port 53, you may need to terminate the application before the Client Agent is able to start.
Applications that make use of the Apple Virtualization Framework are known to sometimes occupy this port under
the name `_mdnsresponder`. If you have any virtualization software, you may need to turn it off before using
the Client Agent.
</Tab>
<Tab heading="Windows" group="windows">
As a privileged user, you can open the **Resource Monitor** and inspect the **Network** > **Listening Ports** section to find any applications that use port 53.
</Tab>
</Tabs>
Once you have identified which other software is using the port, you can stop it and try to start the Client Agent again.
### failed to refresh alias cache: error="fetching resolvable aliases: error performing client request during List call"
This usually implies that there is a problem reaching the internet or the Boundary controller.
The error is related to the periodic updating of aliases used by the Client Agent to know whether a DNS request matches an alias or not.
HashiCorp recommends that you pause the Client Agent and examine the status and logs for further errors:
```shell-session
$ boundary client-agent pause
```
Follow the troubleshooting steps to understand why the Client Agent is not able to reach the controller.
### sendmsg: broken pipe
On MacOS versions 15.1 and 15.2, the firewall may incorrectly block the Client Agent from sending DNS responses. To resolve this issue,
upgrade to MacOS version 15.3 or later.
It may be neccessary to explicitly allow the `boundary-client-agent` process access to incoming network connections.
From the Firewall options in System Settings, toggle the `boundary-client-agent` to **Allow incoming connections**.
### WARNING! Remote host indentification has changed! It is possible that someone is doing something nasty!
This error arises when you use an alias to connect to an SSH target after the first successful connection using that alias. The issue occurs because Boundary workers generate a new host key on every new SSH connection. You can safely ignore the warning using the `StrictHostKeyChecking=no` command line option:
```shell-session
$ ssh -o StrictHostKeyChecking=no targetalias.boundary.dev
```
You can also remove the existing server host key from the `~/.ssh/known_hosts` file to avoid the error.
### This site can't be reached... DNS_PROBE_FINISHED_NXDOMAIN
This error occurs when you have authenticated to Boundary and have a target that is configured with an alias.
When you copy the alias from the **Target** page and paste it in the browser, you receive the error.
The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."
A conflicting service may be preventing the Client Agent from receiving DNS requests.
The service may be bound to port 53.
Restarting your computer may resolve the conflict.
### error when attempting to resume... bind address already in use: invalid state transition
This error occurs when you have authenticated to Boundary and have a target that is configured with an alias.
When you attempt to use the alias to connect to the target, you receive the error message in Boundary Desktop.
The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."
A conflicting service may be preventing the Client Agent from receiving DNS requests.
The service may be bound to port 53.
Restarting your computer may resolve the conflict.
## Transparent sessions known issues
Refer to the following table for known issues with the Client Agent that may affect transparent sessions:
| Issue | Description |
| ----- | ----------- |
| SSH connection fails with man-in-the-middle warning | On Linux systems, the initial transparent session may be successful, but any subsequent connections prompt a warning that you may be experiencing a man-in-the-middle attack. <br /><br /> For more information, refer to [WARNING! Remote host indentification has changed! It is possible that someone is doing something nasty!](/boundary/docs/api-clients/client-agent#warning-remote-host-indentification-has-changed-it-is-possible-that-someone-is-doing-something-nasty) in the **Common error messages** section.|
| Boundary Client Agent authentication does not persist across restarts | When you reboot, you are required to re-authenticate to the Client Agent before you can use transparent sessions. |
| Windows installer prompts for restart | When you install Boundary, the Windows installer occasionally prompts you to restart your computer, however it is not necessary. |
| Boundary Client Agent resumes on reboot | If the Client Agent is paused and the machine is rebooted, the Client Agent will be resumed after the reboot. |
| Single-word aliases do not work on Windows | If you create an alias consisting of a single word without a dot (`.`), the alias will not work on Windows. |
| Windows installer does not support partial installations | The Windows installer fails to start the Client Agent if the Desktop client is not installed at the same time. |
| Alias connection failures inside containers/VMs | Using transparent sessions rely on network access to the local network of the computer the Client Agent is running on. Network enclaves such as those created by Docker containers and VMs cannot reach this network. |
| DNS lookup is broken on MacOS 15.1 and 15.2 | MacOS 15.1 and 15.2 may incorrectly block DNS lookups for the Client Agent. This issue is resolved in MacOS 15.3 and later. |
website/content/docs/api-clients/client-cache.mdx → website/content/docs/client-cache/index.mdx
View File
File renamed without changes.
website/content/docs/commands/aliases/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary aliases list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `scope-id=<string>` - The scope from which to list the aliases.
website/content/docs/commands/auth-tokens/list.mdx
+1 -1
View File
@@ -75,7 +75,7 @@ $ boundary auth-tokens list [options] [args]
- `-filter` `(string: "")` - If set, the list operation is filtered before it is returned.
The filter operates against each item in the list.
We recommend that you use single quotes, as filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, the list operation is applied recursively into child scopes, if the type supports it.
The default value is `false`.
website/content/docs/commands/credential-libraries/list.mdx
+1 -1
View File
@@ -57,7 +57,7 @@ You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_
- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `list_token` (optional) - An opaque token that is returned from the previous `list` response.
If you do not supply a value, pagination starts from the beginning.
- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results.
website/content/docs/commands/credential-stores/list.mdx
+1 -1
View File
@@ -53,7 +53,7 @@ $ boundary credential-stores list [options] [args]
- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, the list operation is applied recursively into child scopes, if supported by the type.
The default value is `false`.
- `-scope-id ``(string: "")` - The scope in which to make the request.
website/content/docs/commands/credentials/list.mdx
+1 -1
View File
@@ -76,7 +76,7 @@ You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_
- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `list_token` (optional) - An opaque token that is returned from the previous `list` response.
If you do not supply a value, pagination starts from the beginning.
- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results.
website/content/docs/commands/database/init.mdx
+2 -2
View File
@@ -13,10 +13,10 @@ The `database init` command initializes Boundary's database.
## Examples
The following example initializes a Boundary's database with the configuration specified in the `/etc/boundary/controller.hcl` file:
The following example initializes a Boundary's database with the configuration specified in the `/etc/boundary.d/controller.hcl` file:
```shell-session
$ boundary database init -config=/etc/boundary/controller.hcl
$ boundary database init -config=/etc/boundary.d/controller.hcl
```
The `controller.hcl` file contains the database URL.
website/content/docs/commands/database/migrate.mdx
+1 -1
View File
@@ -16,7 +16,7 @@ The `database migrate` command migrates the Boundary database within an enclosin
The following example migrates Boundary's database to the database URL specified in the controller configuration file:
```shell-session
$ boundary database migrate -config=/etc/boundary/controller.hcl
$ boundary database migrate -config=/etc/boundary.d/controller.hcl
```
## Usage
website/content/docs/commands/groups/list.mdx
+1 -1
View File
@@ -83,7 +83,7 @@ $ boundary groups list [options] [args]
- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `-scope-id ``(string: "")` - The scope from which to list the groups.
website/content/docs/commands/host-catalogs/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary host-catalogs list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
- `-scope-id=<string>` - The scope from which you want to list host catalogs.
The default scope is `global`.
website/content/docs/commands/host-sets/list.mdx
+1 -1
View File
@@ -34,7 +34,7 @@ $ boundary host-sets list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-host-catalog-id=<string>` - The host catalog resource to use to produce the list.
You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable.
- `list_token` (optional) - An opaque token that is returned from the previous `list` response.
website/content/docs/commands/hosts/list.mdx
+1 -1
View File
@@ -34,7 +34,7 @@ $ boundary hosts list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-host-catalog-id=<string>` - The host catalog resource to use to produce the list.
You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable.
- `list_token` (optional) - An opaque token that is returned from the previous `list` response.
website/content/docs/commands/index.mdx
+1 -3
View File
@@ -5,7 +5,7 @@ description: >-
Learn about Boundary's CLI command structure and behavior. View standard connection options, client options, and environment variables.
---
# CLI
# Boundary CLI overview
Boundary's CLI has predictable behavior throughout its various commands. This
page details the common patterns used to help you make better use
@@ -111,7 +111,6 @@ Available keyring types include:
</Tab>
</Tabs>
## Map to collections and sub-types
Generally speaking, Boundary's CLI commands map to the collections they operate
@@ -287,7 +286,6 @@ provide the token in subsequent commands.
- `-format` `(string: "")` - The given format to print the output. Valid
formats are `table` or `json`. The default value is `table`. You can also specify the format using the `BOUNDARY_CLI_FORMAT` environment variable.
## Environment variables
The CLI reads the following environment variables to set behavioral defaults.
website/content/docs/commands/managed-groups/list.mdx
+1 -1
View File
@@ -36,7 +36,7 @@ You can also specify the auth method using the **BOUNDARY_AUTH_METHOD_ID** envir
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `list_token` (optional) - An opaque token that is returned from the previous `list` response.
If you do not supply a value, pagination starts from the beginning.
- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results.
website/content/docs/commands/policies/create.mdx
+1 -1
View File
@@ -14,7 +14,7 @@ Command: `boundary policies create`
The `boundary policies create` command lets you create Boundary policies.
Storage policies codify how long session recordings must be kept and when they should be deleted.
For more information, refer to the [storage policies](/boundary/docs/concepts/domain-model/storage-policy) documentation.
For more information, refer to the [storage policies](/boundary/docs/domain-model/storage-policy) documentation.
## Example
website/content/docs/commands/policies/index.mdx
+1 -1
View File
@@ -14,7 +14,7 @@ Command: `boundary policies`
The `policies` command lets you perform operations on Boundary policies.
Storage policies codify how long session recordings must be kept and when they should be deleted.
For more information, refer to the [storage policies](/boundary/docs/concepts/domain-model/storage-policy) documentation.
For more information, refer to the [storage policies](/boundary/docs/domain-model/storage-policy) documentation.
## Example
website/content/docs/commands/policies/list.mdx
+1 -1
View File
@@ -37,7 +37,7 @@ $ boundary policies list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `scope-id=<string>` - The scope from which to list policies.
website/content/docs/commands/policies/update.mdx
+1 -1
View File
@@ -14,7 +14,7 @@ Command: `boundary policies update`
The `boundary policies update` command lets you update Boundary policies.
Storage policies codify how long session recordings must be kept and when they should be deleted.
For more information, refer to the [storage policies](/boundary/docs/concepts/domain-model/storage-policy) documentation.
For more information, refer to the [storage policies](/boundary/docs/domain-model/storage-policy) documentation.
## Example
website/content/docs/commands/roles/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary roles list [options] [args]
- `-filter=<string>` - If set, filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `-scope-id=<string>` - The enclosing scope from which you want to list the roles.
website/content/docs/commands/scopes/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary scopes list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `-scope-id=<string>` - The enclosing scope from which to list the scopes.
website/content/docs/commands/server.mdx
+1 -1
View File
@@ -51,7 +51,7 @@ $ boundary server -config="/home/ubuntu/boundary/downstream-worker.hcl"
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary server -config=/etc/boundary/controller.hcl
$ boundary server -config=/etc/boundary.d/controller.hcl
```
</CodeBlockConfig>
website/content/docs/commands/sessions/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary sessions list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-include-terminated` - If set, Boundary includes terminated sessions in the `list` results.
The default value is `false`.
This field has been deprecated and will be removed from a future release.
website/content/docs/commands/storage-buckets/list.mdx
+1 -1
View File
@@ -37,7 +37,7 @@ $ boundary storage-buckets list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `scope-id=<string>` - The scope from which to list storage buckets.
website/content/docs/commands/targets/list.mdx
+1 -1
View File
@@ -35,7 +35,7 @@ $ boundary targets list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `scope-id=<string>` - The scope from which to list the targets.
website/content/docs/commands/users/list.mdx
+1 -1
View File
@@ -34,7 +34,7 @@ $ boundary users list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before it is returned.
The filter operates against each item in the list.
We recommend that you use single quotes, as filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `-recursive` - If set, runs the list operation recursively into child scopes, if the type supports it.
The default value is `false`.
- `-scope-id=<string>` - The scope that contains the users you want to list.
website/content/docs/commands/workers/list.mdx
+1 -1
View File
@@ -34,7 +34,7 @@ $ boundary workers list [options] [args]
- `-filter=<string>` - If set, Boundary filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
Refer to the [Filtering and listing resources documentation](/boundary/docs/filtering) for more details.
- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `scope-id=<string>` - The scope from which to list the workers.
website/content/docs/common-workflows/manage-scopes.mdx
+2 -2
View File
@@ -6,7 +6,7 @@ description: How to manage Boundary scopes
# Manage Scopes
[Scopes](/boundary/docs/concepts/domain-model/scopes) are a foundational part of Boundary. They allow users to partition resources and assign ownership of resources to principals. There are three types of scopes within Boundary:
[Scopes](/boundary/docs/domain-model/scopes) are a foundational part of Boundary. They allow users to partition resources and assign ownership of resources to principals. There are three types of scopes within Boundary:
1. Global (`global`)
2. Org
@@ -18,7 +18,7 @@ These are in a hierarchy:
- Under the `global` scope there can be many org scopes. These are used to hold IAM-related resources and project scopes.
- Under each org scope can be many project scopes. These are used to hold infrastructure-related resources.
Some resources can only be associated with a specific level of scope. As an example, [Targets](/boundary/docs/concepts/domain-model/targets) can only be contained within a project scope. Other resources can be contained by multiple scopes. For example, users can be created within the `global` scope or an org-level scope. See the [domain model](/boundary/docs/concepts/domain-model) for detailed resource specific information.
Some resources can only be associated with a specific level of scope. As an example, [Targets](/boundary/docs/domain-model/targets) can only be contained within a project scope. Other resources can be contained by multiple scopes. For example, users can be created within the `global` scope or an org-level scope. See the [domain model](/boundary/docs/domain-model) for detailed resource specific information.
In this example, we're going to create two scopes, an org and a project.
website/content/docs/common-workflows/manage-sessions.mdx
+1 -1
View File
@@ -6,7 +6,7 @@ description: How to manage Boundary sessions
# Manage Sessions
[Sessions](/boundary/docs/concepts/domain-model/sessions) are Boundary resources created when connecting to a [Target](/boundary/docs/concepts/domain-model/targets). A target allows Boundary users to define an endpoint with a protocol and default port to establish a session. Unless specified with a `-host-id` flag when establishing a session, Boundary will choose one [Host](/boundary/docs/concepts/domain-model/hosts) from the target's [Host Sets](/boundary/docs/concepts/domain-model/host-sets) to connect to at random.
[Sessions](/boundary/docs/domain-model/sessions) are Boundary resources created when connecting to a [Target](/boundary/docs/domain-model/targets). A target allows Boundary users to define an endpoint with a protocol and default port to establish a session. Unless specified with a `-host-id` flag when establishing a session, Boundary will choose one [Host](/boundary/docs/domain-model/hosts) from the target's [Host Sets](/boundary/docs/domain-model/host-sets) to connect to at random.
In this section, we'll show you the basics of how to start a session, view the session details, and cancel a session in Boundary using the CLI.
website/content/docs/common-workflows/manage-targets.mdx
+1 -1
View File
@@ -6,7 +6,7 @@ description: How to manage Boundary targets
# Manage Targets
[Targets](/boundary/docs/concepts/domain-model/targets) are Boundary resources which contain one or more [Host Sets](/boundary/docs/concepts/domain-model/host-sets). A target allows Boundary users to define an endpoint with a default port and a protocol to establish a session. Unless specified with a `-host-id` flag, Boundary will choose one [Host](/boundary/docs/concepts/domain-model/hosts) in the host set to connect to at random.
[Targets](/boundary/docs/domain-model/targets) are Boundary resources which contain one or more [Host Sets](/boundary/docs/domain-model/host-sets). A target allows Boundary users to define an endpoint with a default port and a protocol to establish a session. Unless specified with a `-host-id` flag, Boundary will choose one [Host](/boundary/docs/domain-model/hosts) in the host set to connect to at random.
In this section, we'll show you the basics of how to define a host, host set, and a target in Boundary on the CLI, the admin console, and using our [Terraform provider](https://github.com/hashicorp/terraform-provider-boundary).
website/content/docs/concepts/aliases.mdx
+2 -41
View File
@@ -27,45 +27,6 @@ The existence of an alias for a Boundary resource does not change how permission
Separating the permissions from aliases and destination resources means a different set of people can manage the aliases than the people who have permission to operate on targets. For example, you may have a project with a sensitive set of targets. You can configure Boundary to allow a select few users to manage those targets, while a different group of users manage the aliases.
## Naming conventions
## More information
An alias is a globally unique, DNS-like string that is associated with a destination resource. The alias `value` parameter does not have to be delimited by a suffix, and can be just a hostname.
Examples of valid aliases include `database.boundary` and `webserver.boundary`.
### Single word aliases and transparent sessions
HashiCorp recommends that you do not use single-word aliases such as `webserver` as opposed to `webserver.boundary`, because single-word aliases do not work intuitively on Windows.
Windows DNS resolution does not support resolving unqualified single word DNS hostnames. You can make the hostname fully qualified, but is not intuitive to most users.
For example the following hostname works:
```
ssh mytarget.
```
But this hostname does not work:
```
ssh mytarget
```
For this reason, if you expect any Windows users to use an alias, it should contain a dot (`.`) anywhere in the value.
Refer to the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information.
### HTTPS websites
If you create an alias for a website that uses HTTPS, the alias must match the website's hostname.
You may receive connection errors if the alias does not match the website's hostname exactly.
For example, if you want to create an alias to connect to https://www.hashicorp.com, you must name the alias `www.hashicorp.com`.
## Scopes
You can only create aliases in the `global` scope. However, you can associate aliases with targets or hosts from any scope. Support for additional resource types may be added in the future.
If you delete a project, Boundary clears the `destination_id` parameter for any aliases that resolve to targets in that project, so that they no longer function.
Refer to the [Configure aliases and transparent sessions](/boundary/docs/configuration/target-aliases) pages to learn more.
Refer to [Overview of aliases](/boundary/docs/targets/configuration) to learn about configuring aliases.
website/content/docs/concepts/auditing.mdx
+6 -342
View File
@@ -25,9 +25,7 @@ Further, security teams seek to prevent incidents and proactively identify poten
## Session recording
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Boundary provides auditing capabilities via [session recording](/boundary/docs/concepts/domain-model/session-recordings).
Boundary provides auditing capabilities via session recording.
In Boundary, a session represents a set of connections between a user and a host from a target.
The session begins when an authorized user requests access to a target, and it ends when that access is terminated.
All sessions have a fixed time limit, and all connections are proxied through a worker.
@@ -35,345 +33,11 @@ All sessions have a fixed time limit, and all connections are proxied through a
Sessions are recorded by workers.
Workers are the proxy between an end user and a target.
No session data is routed through a controller during the recording stage.
The worker stores the session recording on local disk during the recording phase, and then moves the recording to the external object store when the session is terminated. Session recordings are stored in the [BSR](#bsr-directory-structure) (Boundary Session Recording) format.
Any credentials needed to access the external object store are passed from the controller to the recording worker when the session is established.
The worker stores the session recording on local disk during the recording phase, and then moves the recording to the external object store when the session is terminated. Session recordings are stored in the BSR (Boundary Session Recording) format.
In a multi-hop session, the worker that is configured to access the external object store is the worker that records the session.
If no worker can access the storage backend, the session is canceled and an error is returned.
## More information
You view session recordings with a session player that runs in a web browser.
The session player is an aggregation of web components that work together to present the different parts of a session recording as a logical whole.
A controller retrieves the contents of a recording from a worker with access to the external object store.
The controller decodes the contents of the recording into a format that is usable by the player.
The player then retrieves the data from the controller.
Refer to the following topics for more information:
### Session recording audit events
Boundary emits audit events for actions performed by users. Here are **some** of the possible event field types that are emitted:
- `timestamp` - The timestamp of the event
- `auth` - Authentication information about the user who performed the action.
- `response.details.item.connection_recordings.`
- `id` - Session recording ID.
- `channel_recordings.id` - Session recording channel ID.
- `start_time.seconds` - Start time of session recording.
- `end_time.seconds` - End time of session recording.
- `bytes_up` - Upload bytes during session.
- `bytes_down` - Download bytes during session.
- `channel_recordings.duration.seconds`- Length of time a session took, recorded in seconds.
- `request_info.client_ip` - The client IP address used by the user.
- `response.details.item.create_time_values.`
- `target.name` - The name of the targets.
- `target.id` - The ID of the target accessed during the recording.
- `target.type` - The type of protocol used.
- `target.scope.name` - Name of the scope the target accessed belongs to.
- `target.scope.parent_scope_id` - Parent ID of the scope the target accessed belongs to.
- `response.details.item.Attrs.SshTargetAttributes.`
- `storage_bucket_id.value` - Storage bucket ID attached to a target that is used for storing session recordings.
- `enable_session_recording.value` - Determines if session recording is enabled on a target.
## Storage buckets
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
A resource known as a [storage bucket](/boundary/docs/concepts/domain-model/storage-buckets) is used to store the recorded sessions.
The storage bucket represents a bucket in an external object store.
At this time, the only supported storage for storage buckets is AWS S3.
In AWS S3, a storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket, such as the secret key.
Before you can use a storage bucket to record sessions, you must configure a worker with local storage to act as a cache.
The entire recording is written to the local storage cache before it is uploaded.
Once the session is complete, the files are automatically synced with the external storage bucket and deleted from the worker's local storage.
A storage bucket exists in either the Global scope or an Org scope.
A storage bucket that is associated with the Global scope can be associated with any target.
However, a storage bucket in an Org scope can only be associated with targets in a project from the same Org scope.
Any storage buckets associated with an Org scope are deleted when the Org itself is deleted.
Deleting a storage bucket in Boundary does not delete the bucket in the external object store, nor does it delete the recorded sessions in the bucket.
The storage bucket's lifecycle does not affect the lifecycle of the bucket in the external object store.
Any session recording metadata that is attached to the storage bucket is deleted when the storage bucket is deleted.
## BSR directory structure
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format.
It contains all the data transmitted between a user and a target during a single session.
Boundary creates the top-level directory of the BSR as `<sessionRecordingID>.bsr`. This top level directory contains session summary
information and subdirectories for connections.
A BSR connections directory contains a summary of connections, as well as inbound and outbound requests.
If you use a multiplexed protocol, there are subdirectories for the channels.
Every directory contains a SHA256SUMS and SHA256SUMS.sig file, to be used for cryptographically verifying the contents of
that directory. The SHA256SUMS file contains rows of file names paired with a checksum for file contents. The
SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR’s private key. For more information on verifying a
session recording, refer to [Validating the integrity of session recordings](/boundary/docs/operations/session-recordings/validate-session-recordings).
The example BSR below is for a multiplexed session recording with the ID `sr_iNCdGSREeX`. The session recording contains one connection,
`cr_3bB78W53Y9`. Connection `cr_3bB78W53Y9` contains two channels, `chr_VUnVuVnITu` and `chr_nITuVUnVuV`.
The files in each directory are explained in the following sections.
```
└── sr_iNCdGSREeX.bsr
├── SHA256SUM
├── SHA256SUM.sig
├── bsrKey.pub
├── pubKeyBsrSignature.sign
├── pubKeySelfSignature.sign
├── session-meta.json
├── session-recording-summary.json
├── session-recording.meta
├── wrappedBsrKey
├── wrappedPrivKey
├── cr_3bB78W53Y9.connection
│ ├── SHA256SUM
│ ├── SHA256SUM.sig
│ ├── connection-recording-summary.json
│ ├── connection-recording.meta
│ ├── requests-inbound.data
│ ├── requests-outbound.data
│ ├── chr_VUnVuVnITu.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ ├── chr_nITuVUnVuV.channel
│ │ ├── SHA256SUM
│ │ ├── SHA256SUM.sig
│ │ ├── channel-recording-summary.json
│ │ ├── channel-recording.meta
│ │ ├── messages-inbound.data
│ │ ├── messages-outbound.data
│ │ ├── requests-inbound.data
│ │ └── requests-outbound.data
│ └──
└──
```
### BSR Session folder
A BSR session folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `bsrKey.pub` is the public ed25519 key.
- `pubKeySelfSignature.sign` is a self-signature of the plaintext public ed25519 key created with its private key.
- `pubKeyBsrSignature.sign` is a signature of the plaintext public ed25519 key created with the BSR key.
- `wrappedBsrKey` is the BSR key wrapped by the external KMS AES-GCM key that you configure.
- `wrappedPrivKey` is the private ed25519 key wrapped by the external KMS AES-GCM key that you configure.
- `session-meta.json` is a JSON file that contains metadata about the session, including the session id, endpoint,
user, target, host, worker, and credentials used to access the target. The intention of this file is to provide all information
relevant to the recorded session so that the BSR provides a complete snapshot of a session even in the absence of the Boundary
control plane.
- `session-recording.meta` is a plaintext file that contains metadata about the session, including the session id, protocol,
and a connection ids. For each connection id listed, there should be a corresponding connection directory in the session directory.
- `session-recording-summary.json` is a JSON file that contains a summary of the session recording, including the session id, connection count,
start time, end time, and any errors encountered during recording of the session.
`session-recording.meta` file example:
```
id: sr_iNCdGSREeX
protocol: BSSH
connection: cr_3bB78W53Y9.connection
```
`session-recording-summary.json` file example:
```
{
"Id": "sr_iNCdGSREeX",
"ConnectionCount": 1,
"StartTime": "2023-09-19T15:05:39.343307163Z",
"EndTime": "2023-09-19T15:08:02.953159598Z",
"Errors": ""
}
```
`session-meta.json` file example:
```
{
"PublicId": "s_HQbVb8fJaM",
"Endpoint": "ssh://openssh-server:2222",
"User": {
"PublicId": "u_5Ry4oDiEVp",
"Scope": {
"PublicId": "global",
"Name": "global",
"Description": "Global Scope",
"Type": "global",
"ParentId": "",
"PrimaryAuthMethodId": "ampw_CdIa5KR9iw"
},
"Name": "admin",
"Description": "Initial admin user within the \"global\" scope"
},
"Target": {
"PublicId": "tssh_TIx4ENZMdA",
"Scope": {
"PublicId": "p_7Qe46uNMYX",
"Name": "session-recording-project",
"Description": "",
"Type": "project",
"ParentId": "o_yK7GoA6OG2",
"PrimaryAuthMethodId": ""
},
"Name": "session-recording-target",
"Description": "",
"DefaultPort": 2222,
"DefaultClientPort": 0,
"SessionMaxSeconds": 28800,
"SessionConnectionLimit": -1,
"WorkerFilter": "",
"EgressWorkerFilter": "",
"IngressWorkerFilter": "\"pki\" in \"/tags/type\"",
"EnableSessionRecording": true,
"StorageBucketId": "sb_vqn871JdQf"
},
"Worker": {
"PublicId": "w_ogOQt0rsuQ",
"Version": "0.13.0",
"Sha": ""
},
"StaticHost": null,
"DynamicHost": null,
"StaticJSONCredentials": null,
"StaticUsernamePasswordCredentials": [
{
"PublicId": "credup_gdzeB5UWJv",
"Name": "",
"Description": "",
"Username": "username",
"PasswordHmac": "PasswordHmac,
"Purposes": [
"injected_application"
],
"CredentialStore": {
"PublicId": "csst_agwIT97uZ7",
"ProjectId": "p_7Qe46uNMYX",
"Name": "ssh static store",
"Description": "SSH Static Cred store"
}
}
],
"StaticSshPrivateKeyCredentials": null,
"VaultGenericLibraries": null,
"VaultSshCertificateLibraries": null
}
```
### BSR Connection folder
A BSR connection folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `connection-recording.meta` is a plaintext file that contains metadata about the connection, including the connection id,
requests seen, channel ids, and any errors seen. For each channel id listed, there should be a corresponding channel directory in the connection directory.
- `connection-recording-summary.json` is a JSON file that contains a summary of the connection, including the connection id,
start time, end time, bytes up, bytes down, and any errors encountered during recording the connection.
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the connection.
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the connection.
`connection-recording.meta` file example:
```
id: cr_W53Y93bB78
requests: outbound
requests: inbound
channel: chr_uVVuUITnVn.channel
error: error message would be appear here
```
`connection-recording-summary.json` file example:
```
{
"Id": "cr_W53Y93bB78",
"ChannelCount": 1,
"StartTime": "2023-07-13T20:21:49.164105381Z",
"EndTime": "2023-07-13T20:22:37.241911112Z",
"BytesUp": 125,
"BytesDown": 748,
"Errors": null
}
```
### BSR Channel folder
A BSR connection folder contains the following files:
- `SHA256SUM.sig` is a plaintext file that contains rows of file names paired with a checksum for file contents.
- `SHA256SUM.sig` is a signature of the plaintext `SHA256SUM` file created with the private key.
- `channel-recording.meta` is a plaintext file that contains metadata about the channel, including the channel id,
inbound and outbound requests seen, and inbound and outbound messages seen.
- `channel-recording-summary.json` is a JSON file that contains a summary of the channel, including the channel id,
start time, end time, bytes up, bytes down, channel type, session program, subsystem name (if applicable), exec program (if applicable),
and file transfer direction (if applicable).
- `requests-inbound.data` is a binary file containing all inbound SSH request messages transmitted for the channel.
- `requests-outbound.data` is a binary file containing all outbound SSH request messages transmitted for the channel.
- `messages-inbound.data` is a binary file containing all inbound SSH data transmitted for the channel.
- `messages-outbound.data` is a binary file containing all outbound SSH data transmitted for the channel.
`channel-recording.meta` file example:
```
id: chr_uVVuUITnVn
channelType: session
messages: outbound
requests: outbound
messages: inbound
requests: inbound
```
`channel-recording-summary.json` file example:
```
{
"ChannelSummary": {
"Id": "chr_uVVuUITnVn",
"ConnectionRecordingId": "cr_W53Y93bB78",
"StartTime": "2023-07-13T20:21:49.230916214Z",
"EndTime": "2023-07-13T20:22:37.229379944Z",
"BytesUp": 125,
"BytesDown": 748,
"ChannelType": "session"
},
"SessionProgram": "shell",
"SubsystemName": "",
"ExecProgram": "",
"FileTransferDirection": "not applicable"
}
```
For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording).
## Read a BSR data file
BSR data files are where all the data transmitted during a session is stored. BSR data files
have the file suffix `.data` and are binary files written in network byte or big-endian order. The first eight bytes of a
BSR data file always contains the following signature, which identifies the file as a BSR file: `"\x89BSR\r\n\x1a\n"`.
Following the BSR signature, a BSR file contains “chunks” of data. Each chunk contains the same basic metadata information:
length, protocol, chunk type, direction, and a timestamp. The chunk type indicates the expected data payload. The first
chunk in a BSR file is the header chunk, and the last chunk in a BSR file is the EOF chunk. The remaining
chunks in the file depend on the protocol identified in the BSR header.
The only protocol currently supported for session recording is SSH. Data files for SSH are prefixed with either `messages-`
or `requests-`, and suffixed with either `inbound` or `outbound` to indicate the direction the data came from. Message
files contain raw data from an SSH session and contain a header chunk, data chunks, and an EOF chunk. Request files
contain a header chunk, SSH request message chunks, and an EOF chunk.
SSH request message chunks follow the SSH connection and channel request definitions. Boundary populates these chunks
using a protobuf definition provided here: [SSH Chunks](https://github.com/hashicorp/boundary/blob/main/internal/bsr/proto/ssh/v1/ssh_chunks.proto).
Boundary session recording playback generates an asciinema from a session channel’s `messages-outbound.data` file. For more
information on finding and viewing BSR data using the asciinema, refer to [Find and view recorded sessions](https://developer.hashicorp.com/boundary/docs/operations/session-recordings/manage-recorded-sessions).
While Boundary does not currently provide tooling to read other BSR .data files, the BSR definition is available in our
[community repository](https://github.com/hashicorp/boundary/tree/main/internal/bsr), and you can use it to develop external tooling.
- [Session recording](/boundary/docs/session-recording)
- [BSR file data structure](/boundary/docs/session-recording/data/bsr-file-structure)
website/content/docs/concepts/credential-management.mdx
+15 -8
View File
@@ -10,9 +10,7 @@ description: >-
When users connect to a remote machine, they typically need a set of credentials for authentication.
After they connect to the machine, they may also require another set of credentials to access services or other machines within the network.
There are two credential management paradigms in Boundary, [credential brokering](#credential-brokering) and [credential injection](#credential-injection).
To configure credential brokering or credential injection with static credentials, refer to [Create a static credential store](/boundary/docs/configuration/credential-management/static-cred-boundary) and [Create a Vault credential store](/boundary/docs/configuration/credential-management/static-cred-vault).
There are two credential management paradigms in Boundary, credential brokering and credential injection.
## Credential brokering
@@ -66,10 +64,6 @@ In this scenario, while the brokered credential may not be visible to the user,
Additionally, with Vault's dynamic secrets engine, an administrator could configure their environment such that secrets are essentially one-time passwords, as the credentials are revoked after the session is terminated.
Learn more about [credential brokering](/boundary/tutorials/hcp-getting-started/hcp-getting-started-credentials).
Learn more about the [Vault dynamic secrets engine](/vault/docs/secrets).
## Credential injection
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
@@ -122,4 +116,17 @@ Upon connecting to the worker, the worker attempts to establish a remote session
If the user is not authorized to access the target, the credentials are not injected on their behalf, nor are the credentials brokered back to them.
Learn more about [credential injection](/boundary/tutorials/hcp-administration/hcp-ssh-cred-injection).
## Tutorial
Refer to the [Broker static credentials to your first target](/boundary/tutorials/get-started-hcp/hcp-getting-started-credentials) tutorial to practice configuring credential brokering.
Refer to the [Manage SSH keys with HCP Boundary and Vault](/boundary/tutorials/hcp-administration/hcp-ssh-cred-injection) tutorial to practice configuring credential injection.
## More information
To configure credential brokering or credential injection with static credentials, refer to the following topics:
- [Create a static credential store](/boundary/docs/credentials/static-cred-boundary)
- [Create a Vault credential store](/boundary/docs/credentials/static-cred-vault).
Refer to [Secrets engines](/vault/docs/secrets) to learn more about the Vault dynamic secrets engine.
website/content/docs/concepts/domain-model/aliases.mdx
-36
View File
@@ -1,36 +0,0 @@
---
layout: docs
page_title: Alias resource
description: >-
Learn about using the alias resource to transparently connect to targets without having to provide the target ID or target name and scope ID.
---
# Aliases
An alias is a globally unique, DNS-like string that is associated with a destination resource.
Examples of valid aliases are `webserver` and `webserver.boundary`.
You can establish a session to a target by referencing its alias, instead of having to provide a target ID or target name and scope ID.
For example, if you have an alias `boundary.dev`, you can use it to connect to a target with the following command: `boundary connect ssh boundary.dev`.
## Attributes
Aliases have the following attributes:
- `-description=<string>` - Specifies the optional description you want to use to describe the alias for identification purposes.
- `-destination-id=<string>` - Specifies the ID of the target that the alias points to.
- `-name=<string>` - Specifies the optional name you want to use to describe the alias for identification purposes.
- `-scope-id=<string>` - Scope in which to create the alias. The default is `global`.
You can also specify the scope using the BOUNDARY_SCOPE_ID environment variable.
At this time, aliases are only supported for the global scope.
- `-value=<string>` - Specifies the string that you want to use as the alias to represent the target.
The `value` must comply with DNS naming rules.
### Target subtypes
The target subtype has the following additional attributes:
- `-authorize-session-host-id=<string>` - Indicates the host ID to use when you use the alias to authorize a session.
## More information
- [Aliases](/boundary/docs/concepts/aliases)
website/content/docs/concepts/domain-model/index.mdx
-224
View File
@@ -1,224 +0,0 @@
---
layout: docs
page_title: Domain model overview
description: >-
Learn about using the domain model to organize identity and access management and target resources for secure access. Understand how resources work together.
---
# Overview
[HashiCorp Boundary](https://www.boundaryproject.io/) has an extensible domain model that allows administrators to organize IAM (Identity and Access Management) and target resources in a way that best compliments how their organization manages its computing infrastructure. This concept page is a high-level look at scopes, how they work, and their role in the domain model. We will also explore how Boundary approaches IAM and granting access to Targets. For more information about Boundary’s resource types, see the subpages of the Domain Model section.
## Scopes
When conducting threat modeling exercises, it is common practice to mitigate identified risks by reducing their potential blast radius and attack surface. Boundary uses the concept of scopes to help security operators achieve this type of mitigation. A [Scope](/boundary/docs/concepts/domain-model/scopes) can be considered as a container for resources and permissions. Each scope has a permissions boundary that is isolated from other scopes on the same level, creating a defined blast radius.
The diagram below illustrates the relationship between the different levels of scopes.
![](/img/boundary-domain-model-overview.jpg)
The highest-level scope is the [Global Scope](/boundary/docs/concepts/domain-model/scopes#global). Boundary administrators operate on this level to configure and manage Boundary for the entire business. Boundary administrators can also manage child scopes, auth methods, users, groups, roles, and grants.
The intermediate scope level is [Organizations](/boundary/docs/concepts/domain-model/scopes#organizations), also referred to as orgs, which are a child scope of global. Though the implementation may be flexible for organization scopes, we recommend scoping by business units in this case. Scoping by business unit provides a clear separation of concerns for each business unit. Creating organizations for the development, operations, and support teams would be an example.
The lowest scope level is the [Project](/boundary/docs/concepts/domain-model/scopes#projects). An organization’s scope may have as many projects as required based on its business workflows. To expand on the example used earlier, the development team’s organization can also have project scopes for their different products.
For example, they could have the following project scopes:
- Product 1
- Product 2
- Product 3
## Identity and access management
As mentioned earlier, IAM is handled at the organization and global scope levels. Here, operators can create and manage principals. Principals are entities in Boundary that are either [Users](/boundary/docs/concepts/domain-model/users) or [Groups](/boundary/docs/concepts/domain-model/groups) that may be assigned capabilities.
Users are associated with either the global or an organization’s scope. For better access control management, users may be positioned into groups to ease access control demands. Groups can also contain users from different organizations or global scopes without creating multiple users for a single entity, making permissioning less complicated to implement.
An [Auth Method](/boundary/docs/concepts/domain-model/auth-methods) is the mechanism in Boundary used for authentication. An organization may use numerous authentication methods. Boundary supports Open ID Connect (OIDC) auth methods to delegate authentication to an external identity provider (IDP) - such as Azure Active Directory, Okta, and other OIDC providers - as well as a Boundary-native password auth method. Within an auth method, [Accounts](/boundary/docs/concepts/domain-model/accounts) may be created and associated with users. Once associated with a user, the principal may authenticate in Boundary using the method specified by their auth method. An account for the password auth method consists of a login name and password. A user may be associated with accounts from different auth methods, where they can have both an Azure Active Directory account and an Okta account, for example. In such cases, the user could authenticate with either provider.
## Access management
Boundary’s method of access management starts at the lowest level with Actions. Actions are capabilities that can be performed against Boundary resources. Boundary supports generic Actions such as, Create, Read, Update, Delete, and List. However, there are many more that are resource-type-specific actions that can be used in grants.
The next level of access management is a [Grant](/boundary/docs/concepts/security/permissions#grant-strings). A grant in Boundary contains an action(s) and the resource(s) that the action(s) are permitted to be performed against. This can be thought of like a rule.
For example, a grant can specify the List Action against a specific resource. Grants can specify resource types or resource IDs and may also be implemented as a rule.
The highest-level in Boundary utilizes the concepts of [Roles](/boundary/docs/concepts/domain-model/roles). Roles are a collection of zero or more grants. Roles are assigned to principals (users and groups) and govern what actions they are authorized to perform. Roles belong to a single scope and their lifecycle is dependent on the existence of that scope. Should the scope be deleted, the role would be deleted too. The diagram below illustrates the relationship between the different IAM components within Boundary.
![](/img/component-relationship.png)
## Target and host resources
Boundary exposes endpoints to users as [Targets](/boundary/docs/concepts/domain-model/targets). A target is a resource representing a networked service, with an associated set of permissions, that allows a user to connect and interact with Boundary within a single session. A target may contain references to [Host](/boundary/docs/concepts/domain-model/hosts) sources or an address, and [Credential](/boundary/docs/concepts/domain-model/credentials) sources. Users who access a target create an authorized session to its address or one of its host sources with returned credentials from the target’s credential source.
A target exposes two distinct and mutually exclusive configuration paths for its
representation of a networked service:
- Target with an address
- Target with host sources
A target with an address represents a target that is set up with a single IP
address or DNS name directly on the target resource. This mechanism provides
benefits for new Boundary users and users who do not need the flexibility
provided by Hosts, Host Sets, and Host Catalogs. It is well suited for cases
where there are stand-alone hosts that should not be grouped together and
treated as equal from an access control point of view. Because of its
simplicity, using targets with an address is not recommended when there are a
either a large number of hosts and/or dynamic hosts.
A target with host sources represents a target that has one or more [host
sets][] associated with it. It trades off the simplicity of directly setting an
address on a target with the flexibility and scalability of Hosts, Host Sets and
Host Catalogs for discovering and categorizing networked resources. We recommend
using targets with host sources for setting up Boundary in environments where a
significant number of resources exist.
### Summary of resources
- **[Account][]** :
A resource
that represents a unique set of credentials
issued from a configured [authentication method][]
which can be used to establish the identity of a [user][].
- **[Alias][]** :
A resource
that represents a globally unique, DNS-like string that is
associated with a destination resource, such as a [target][].
- **[Credential][]** :
A data structure containing one or more secrets
that binds an identity to a set of permissions or capabilities
on a [host][] for a [session][].
- **[Credential library][]** :
A resource
that provides [credentials][]
of the same type and same access level
from a single [credential store][].
- **[Credential store][]** :
A resource
that can retrieve, store, and potentially generate [credentials][]
of differing types and differing access levels.
It may also contain [credential libraries][].
- **[Authentication method][]** :
A resource
that provides a mechanism
for [users][] to authenticate to Boundary.
- **[Group][]** :
A resource
that represents a collection of [users][]
which can be treated equally
for the purposes of access control.
- **[Host][]** :
A resource
that represents a computing element with a network address
reachable from Boundary.
- **[Host catalog][]** :
A resource
that contains [hosts][] and [host sets][].
- **[Host set][]** :
A resource
that represents a collection of [hosts][]
which are considered equivalent
for the purposes of access control.
- **[Managed group][]** :
A resource that groups [accounts][] based on criteria
established by a third-party service backing the [authentication method][]. It
can be used as a principal in [roles][].
- **[Role][]** :
A resource
that contains a collection of [permissions][]
which are granted to any principal assigned to the role.
- **[Session][]** :
A set of related connections between a [user][] and a [host][].
A session may include a set of [credentials][]
which define the permissions granted to the [user][] on the [host][] for the duration
of the session.
- **[Session recordings][]** :
A session recording represents a directory structure of files in an external object store that together are the recording of a single [session][] between a [user][] and a [target][].
- **[Scope][]** :
A [permission][] boundary modeled as a container.
- **[Storage bucket][]** :
A storage bucket is used to store [session recordings][].
The storage bucket represents a bucket in an external object store.
- **[Storage policy][]** :
A storage policy defines the rules for storing
[session recordings][] in a [storage bucket][].
The storage policy may specify the retention period for the recordings.
- **[Target][]** :
A resource
that represents a networked service
with an associated set of permissions
a [user][] can connect to
and interact with
through Boundary
by way of a [session][].
- **[User][]** :
A resource
that represents an individual person or entity
for the purposes of access control.
## Next steps
When getting started with Boundary,
the first resource to look at should be [Scopes][].
Every other resources is either contained within a scope,
or contained within another resource
that is itself contained within a scope.
Refer to the [Scopes] section to help you understand the structure of resources within Boundary.
[iam]: https://en.wikipedia.org/wiki/Identity_management
[account]: /boundary/docs/concepts/domain-model/accounts
[accounts]: /boundary/docs/concepts/domain-model/accounts
[alias]: /boundary/docs/concepts/domain-model/aliases
[authentication method]: /boundary/docs/concepts/domain-model/auth-methods
[authentication methods]: /boundary/docs/concepts/domain-model/auth-methods
[credential library]: /boundary/docs/concepts/domain-model/credential-libraries
[credential libraries]: /boundary/docs/concepts/domain-model/credential-libraries
[credential store]: /boundary/docs/concepts/domain-model/credential-stores
[credential stores]: /boundary/docs/concepts/domain-model/credential-stores
[credential]: /boundary/docs/concepts/domain-model/credentials
[credentials]: /boundary/docs/concepts/domain-model/credentials
[group]: /boundary/docs/concepts/domain-model/groups
[groups]: /boundary/docs/concepts/domain-model/groups
[host catalog]: /boundary/docs/concepts/domain-model/host-catalogs
[host catalogs]: /boundary/docs/concepts/domain-model/host-catalogs
[host set]: /boundary/docs/concepts/domain-model/host-sets
[host sets]: /boundary/docs/concepts/domain-model/host-sets
[host]: /boundary/docs/concepts/domain-model/hosts
[hosts]: /boundary/docs/concepts/domain-model/hosts
[managed group]: /boundary/docs/concepts/domain-model/managed-groups
[role]: /boundary/docs/concepts/domain-model/roles
[roles]: /boundary/docs/concepts/domain-model/roles
[scope]: /boundary/docs/concepts/domain-model/scopes
[scopes]: /boundary/docs/concepts/domain-model/scopes
[project]: /boundary/docs/concepts/domain-model/scopes#projects
[session]: /boundary/docs/concepts/domain-model/sessions
[session recordings]: /boundary/docs/concepts/domain-model/session-recordings
[sessions]: /boundary/docs/concepts/domain-model/sessions
[storage bucket]: /boundary/docs/concepts/domain-model/storage-buckets
[storage policy]: /boundary/docs/concepts/domain-model/storage-policy
[target]: /boundary/docs/concepts/domain-model/targets
[targets]: /boundary/docs/concepts/domain-model/targets
[user]: /boundary/docs/concepts/domain-model/users
[users]: /boundary/docs/concepts/domain-model/users
[permission]: /boundary/docs/concepts/security/permissions
[permissions]: /boundary/docs/concepts/security/permissions
website/content/docs/concepts/domain-model/sessions.mdx
-108
View File
@@ -1,108 +0,0 @@
---
layout: docs
page_title: Session resource
description: >-
Learn how the session resource is a set of connections between users and hosts that may include credentials. Understand how sessions are created and terminated.
---
# Sessions
A session is
a set of related [connections][]
between a [user][] and a [host][].
A session may include a set of [credentials][]
which define the permissions granted to the [user][] on the [host][] for the duration
of the session.
A user initiates a session
by requesting access to a [target][].
If a user has the proper [permissions][],
a session is created
and the [expiration time][] and [connection limit][]
are set based on the [target's attributes][].
If the [target][] is associated with [credential libraries][],
[credentials][] are retrieved and returned from each
[credential library][].
A snapshot of the data
relevant to authorizing the session
is also captured and stored in the Boundary data warehouse
when the session is created.
Sessions are created in the [project][] of the corresponding [target][].
Deleting a project will terminate all of the active sessions in the project
but will not effect any session data in the data warehouse.
Historical data in the data warehouse is never deleted.
## Termination
A session is forcefully terminated when one of the following occurs:
- The session reaches the time limit and expires.
- An authorized user manually cancels the session.
- Any resource associated with the session is deleted
or removed from the [target][].
This includes: the [host][], the [host set][], the [host catalog][],
a [credential][], a [credential library][], a [credential store][],
the [target][] itself, the [project][], the [organization][],
the [user][], the user's [account][], or the account's [authentication method][].
In addition to the above,
a session terminates non-forcefully
when the user closes all connections
and no additional connections are allowed
because of a connection limit.
Any [credentials][] associated with the session are revoked when the session is
terminated.
Permissions are only evaluated at session establishment.
Changes to a user's permissions do not effect existing sessions.
## Referenced by
- [Project][]
- [Credential][]
- [Host Set][]
- [Target][]
[expiration time]: /boundary/docs/concepts/domain-model/targets#session_max_seconds
[connection limit]: /boundary/docs/concepts/domain-model/targets#session_connection_limit
[target's attributes]: /boundary/docs/concepts/domain-model/targets#tcp-target-attributes
[account]: /boundary/docs/concepts/domain-model/accounts
[accounts]: /boundary/docs/concepts/domain-model/accounts
[authentication method]: /boundary/docs/concepts/domain-model/auth-methods
[authentication methods]: /boundary/docs/concepts/domain-model/auth-methods
[connections]: /boundary/docs/concepts/domain-model/session-connections
[credential library]: /boundary/docs/concepts/domain-model/credential-libraries
[credential libraries]: /boundary/docs/concepts/domain-model/credential-libraries
[credential store]: /boundary/docs/concepts/domain-model/credential-stores
[credential stores]: /boundary/docs/concepts/domain-model/credential-stores
[credential]: /boundary/docs/concepts/domain-model/credentials
[credentials]: /boundary/docs/concepts/domain-model/credentials
[host catalog]: /boundary/docs/concepts/domain-model/host-catalogs
[host catalogs]: /boundary/docs/concepts/domain-model/host-catalogs
[host set]: /boundary/docs/concepts/domain-model/host-sets
[host sets]: /boundary/docs/concepts/domain-model/host-sets
[host]: /boundary/docs/concepts/domain-model/hosts
[hosts]: /boundary/docs/concepts/domain-model/hosts
[target]: /boundary/docs/concepts/domain-model/targets
[targets]: /boundary/docs/concepts/domain-model/targets
[user]: /boundary/docs/concepts/domain-model/users
[users]: /boundary/docs/concepts/domain-model/users
[organization]: /boundary/docs/concepts/domain-model/scopes#organizations
[organizations]: /boundary/docs/concepts/domain-model/scopes#organizations
[project]: /boundary/docs/concepts/domain-model/scopes#projects
[projects]: /boundary/docs/concepts/domain-model/scopes#projects
[permissions]: /boundary/docs/concepts/security/permissions
## Service API docs
The following services are relevant to this resource:
- [Session Service](/boundary/api-docs/session-service)
## Tutorial
Refer to the [Manage Sessions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-sessions) tutorial to learn how to start, view, and cancel a session.
website/content/docs/concepts/filtering/index.mdx
-113
View File
@@ -1,113 +0,0 @@
---
layout: docs
page_title: Filtering
description: >-
Learn how to use filters to match and find data. Understand how to create filter expressions using matching operators composed with selectors and values.
---
# Filter expressions
Filter expressions can be used by various parts of Boundary to provide useful
functionality. This page describes the overall syntax; see the sub-pages for
information on the specific values available for filtering for various features,
including examples.
Each filter expression has matching operators composed with selectors and
values.
## Create expressions
A single expression is a matching operator with a selector and value. They are
written in plain text format, and Boolean logic and parenthesization are
supported. In general whitespace is ignored, except within literal strings.
### Matching operators
All matching operators use a selector or value to choose what data should be
matched. Each endpoint that supports filtering accepts a potentially different
list of selectors and is detailed in the API documentation for those endpoints.
```text
// Equality & Inequality checks
<Selector> == "<Value>"
<Selector> != "<Value>"
// Emptiness checks
<Selector> is empty
<Selector> is not empty
// Contains checks or Substring Matching
"<Value>" in <Selector>
"<Value>" not in <Selector>
<Selector> contains "<Value>"
<Selector> not contains "<Value>"
// Regular Expression Matching
<Selector> matches "<Value>"
<Selector> not matches "<Value>"
```
### Selectors
Selectors are used by matching operators to create an expression. Inputs to
filter expressions are JSON (or JSON-derived); selectors therefore use [JSON
Pointer](https://tools.ietf.org/html/rfc6901) to select values from the input.
Each selector must be enclosed in quotes and contain a valid JSON Pointer path,
including leading slash (`/`).
```text
// Selects the value `zipzap` from the input `{ "foo": { "bar": "zipzap" } }`
"/foo/bar"
```
### Values
Values are used by matching operators to create an expression. Values can be any
valid selector, a number, or a string. It is best practice to quote values.
Numbers can be base 10 integers or floating point numbers.
When quoting strings, they may either be enclosed in double quotes or backticks.
When enclosed in backticks they are treated as raw strings and escape sequences
such as `\n` will not be expanded.
## Connect expressions
There are several methods for connecting expressions, including
- Logical `or`
- Logical `and`
- Logical `not`
- Grouping with parenthesis
- Matching expressions
```text
// Logical Or - evaluates to true if either sub-expression does
<Expression 1> or <Expression 2>
// Logical And - evaluates to true if both sub-expressions do
<Expression 1 > and <Expression 2>
// Logical Not - evaluates to true if the sub-expression does not
not <Expression 1>
// Grouping - Overrides normal precedence rules
( <Expression 1> )
// Inspects data to check for a match
<Matching Expression 1>
```
Standard operator precedence can be expected for the various forms. For example,
the following two expressions would be equivalent.
```text
<Expression 1> and not <Expression 2> or <Expression 3>
( <Expression 1> and (not <Expression 2> )) or <Expression 3>
```
## Performance
Filters are executed on the controllers and therefore will consume some amount
of CPU time on the controller.
website/content/docs/concepts/filtering/resource-listing.mdx
-87
View File
@@ -1,87 +0,0 @@
---
layout: docs
page_title: Filtering - resource listing
description: >-
Learn how to use filters to reduce the set of resources returned when you perform a list operation. Filtering list results helps you find information.
---
# Filter resource listings
This page describes how to use filters when listing resources. This can be used
to reduce the returned set of resources when performing a list operation.
~> **Note:** This feature is intended to provide a userful service to clients; it does not
affect the database queries generated for the operation and as such is not
designed to provide greater efficiency.
Starting in Boundary 0.1.8, when running a list action, a filter can be
specified. It uses the standard [filter syntax](/boundary/docs/concepts/filtering) used
elsewhere in Boundary. Unless otherwise specified for a given list endpoint, the
list of items being returned is looped through and the filter is run on the JSON
representation of that item. A good way to see what that data looks like is by
looking at representative JSON output on the command line; for example, the
following is the output of `boundary targets list -scope-id p_1234567890 -format json` on a dev instance (piped through `jq` for readability):
```json
[
{
"id": "ttcp_1234567890",
"scope_id": "p_1234567890",
"scope": {
"id": "p_1234567890",
"type": "project",
"name": "Generated project scope",
"description": "Provides an initial project scope in Boundary",
"parent_scope_id": "o_1234567890"
},
"name": "Generated target",
"description": "Provides an initial target in Boundary",
"created_time": "2021-02-24T22:19:50.640476Z",
"updated_time": "2021-02-24T22:19:50.640476Z",
"version": 1,
"type": "tcp",
"session_max_seconds": 28800,
"session_connection_limit": -1,
"attributes": {
"default_port": 22
},
"authorized_actions": [
"read",
"update",
"delete",
"add-host-sources",
"set-host-sources",
"remove-host-sources",
"authorize-session"
]
}
]
```
As the filter tests each entry being returned, it places the data under test
within the filter at `/item`.
On the CLI a filter can be given via `-filter`.
~> **Tip:** Double quotes are part of the filter syntax; when using the CLI, it is likely
easier to surround the filter with single quotes than to deal with escaping
double quotes.
When using the HTTP API, it is a `filter` query parameter.
~> **Tip:** Ensure that the query parameter is properly escaped! Most HTTP libraries will
do this for you. If you're having trouble, try using the `-output-curl-string`
flag with the Boundary CLI:
```
$ boundary targets list -scope-id p_1234567890 -format json -filter '"authorize-session" in "/item/authorized_actions"' -output-curl-string
curl -H "Authorization: Bearer $(boundary config get-token -keyring-type pass -token-name default)" -H "Content-Type: application/json" 'http://127.0.0.1:9200/v1/targets?filter=%22authorize-session%22+in+%22%2Fitem%2Fauthorized_actions%22&scope_id=p_1234567890'
```
Following are some examples.
- Resources in which the user is allowed to run an "update" action:
`"update" in "/item/authorized_actions"`
- Resources matching a name pattern, but only those within an organization
scope: `"/item/name" matches "groupa-*" and "/item/scope/type" == "org"`
website/content/docs/concepts/iam.mdx
+21 -22
View File
@@ -7,42 +7,43 @@ description: >-
# Identity and access management (IAM)
## IAM components
There are 6 key components to Boundary's identity and access management system: **Scopes**, **Auth Methods**, **Accounts**, **Users**, **Groups**, and **Roles**.
### Scopes
[Scopes](/boundary/docs/concepts/domain-model/scopes) can be considered as containers for resources and permissions. Each scope also has a permissions boundary that is isolated from other scopes on the same level. There are three types of scopes:
## Scopes
[Scopes](/boundary/docs/domain-model/scopes) can be considered as containers for resources and permissions. Each scope also has a permissions boundary that is isolated from other scopes on the same level. There are three types of scopes:
- **Global** - The highest-level scope of Boundary where administrators configure and manage Boundary for the entire company.
- **Org (Organization)** - Org scopes are contained in the global scope and are typically used to represent business units, organizations, or departments.
Org scopes can also be used to contain multiple production-level auth methods in separate scopes.
- **Project** - Project scopes are contained in Org scopes and be used to separate different business workflows. For example, projects can be used to represent different teams, products, or environments (test, dev, prod).
### Auth methods
[Auth Methods](/boundary/docs/concepts/domain-model/auth-methods) are resources that authenticate users to
## Auth methods
[Auth methods](/boundary/docs/domain-model/auth-methods) are resources that authenticate users to
Boundary. Auth methods can only be contained by the global or Org scopes. The available auth methods are:
- Username/Password
- [OIDC](/boundary/tutorials/identity-management/oidc-auth)
- LDAP
### Accounts
[Accounts](/boundary/docs/concepts/domain-model/accounts) are resources that represent an authenticated user from a trusted identity provider through a Boundary auth method. Accounts must belong to an auth method, and can be associated with a single Boundary user. Boundary accounts can belong to the global or Org Scopes.
## Accounts
[Accounts](/boundary/docs/domain-model/accounts) are resources that represent an authenticated user from a trusted identity provider through a Boundary auth method. Accounts must belong to an auth method, and can be associated with a single Boundary user. Boundary accounts can belong to the global or Org Scopes.
### Users
[Users](/boundary/docs/concepts/domain-model/users) are resources that represent an individual person or entity for the purposes of
## Users
[Users](/boundary/docs/domain-model/users) are resources that represent an individual person or entity for the purposes of
access control. A user can contain multiple accounts from multiple auth methods, and can belong to the global or Org Scopes.
### Groups
[Groups](/boundary/docs/concepts/domain-model/groups) are resources that represent a collection of users, and can be contained by any
scope. [Managed groups](/boundary/docs/concepts/domain-model/managed-groups) are a special kind of group that syncs with the auth
## Groups
[Groups](/boundary/docs/domain-model/groups) are resources that represent a collection of users, and can be contained by any
scope. [Managed groups](/boundary/docs/domain-model/managed-groups) are a special kind of group that syncs with the auth
method's identity provider to provide up-to-date information.
### Roles
[Roles](/boundary/docs/concepts/domain-model/roles) are resources that contain a collection of
[permissions](/boundary/docs/concepts/security/permissions) which are granted to any principal (user or group) from any scope. Roles
## Roles
[Roles](/boundary/docs/domain-model/roles) are resources that contain a collection of
[permissions](/boundary/docs/rbac/assignable-permissions) which are granted to any principal (user or group) from any scope. Roles
can be contained by any scope, and the permissions can be applied to the same scope or any child scope.
## Access management
You can add users to Boundary using the password auth method or OIDC/LDAP.
### Configure users - username/password
There are 3 steps to adding new users to Boundary using the password auth method:
1. Choose the **scope** and the **auth method** that the user will use to authenticate to Boundary. If the desired auth method does not exist, you must create a new one.
@@ -54,13 +55,13 @@ With the [OIDC](/boundary/tutorials/identity-management/oidc-auth) and LDAP auth
as the auth method. The accounts and users are only created once the user authenticates to Boundary for the first time.
The same applies to OIDC/LDAP [managed groups](/boundary/tutorials/identity-management/oidc-idp-groups).
You can configure the `max_age` in the [OIDC attributes](/boundary/docs/concepts/domain-model/auth-methods#oidc-auth-method-attributes) to indicate to the OIDC provider how much time is allowed to pass until a user is challenged to authenticate again.
You can configure the `max_age` in the [OIDC attributes](/boundary/docs/domain-model/auth-methods#oidc-auth-method-attributes) to indicate to the OIDC provider how much time is allowed to pass until a user is challenged to authenticate again.
However, the user will not be prompted to authenticate until the controller's `auth_token_time_to_live` [parameter](/boundary/docs/configuration/controller#auth_token_time_to_live) has expired.
The default value is 7 days.
To configure time to live in HCP Boundary, refer to [Configure authentication time to live](/hcp/docs/boundary/configure-ttl).
### Grant permissions
## Grant permissions
When setting up access controls for a user, it is important to first consider which scope(s) the user needs access to. Roles give users permission to perform actions through grants strings.
It is recommended to add the user to a group, and then add the group to the role(s), instead of adding the user directly to the role(s). This way, you can manage multiple users at the same time, and it is easier to
change the permissions of the user by adding/removing them from groups. You can manage OIDC/LDAP users and managed groups the same way, directly in the provider.
@@ -87,9 +88,9 @@ Projects.
### Org_A admin
1. The following scopes **each** require a role (ex. “admin”)
- Org_A
- Project_1
- Project_2
- Org_A
- Project_1
- Project_2
2. Each role needs to have the user/group added as a principal
3. Each role needs to have the grants of
@@ -110,7 +111,5 @@ Projects.
- `ids=*;type=target;actions=list,read,authorize-session`
- `ids=*;type=session;actions=read:self,cancel:self,list`
<Tip>
You can use the same roles across “Boundary Admin”, “Org_A Admin”, and “Project_1 Admin” since the scopes and grants are the same. The only difference is
the users/groups that are added to each role.
</Tip>
website/content/docs/concepts/index.mdx
-13
View File
@@ -1,13 +0,0 @@
---
layout: docs
page_title: Concepts
description: >-
Discover resources to help you understand Boundary concepts and architecture.
---
# Concepts
This section covers some concepts that are imporant to understand Boundary usage and operation. Every page in this section is recommended reading for anyone consuming or operating
Boundary. For a glossary of terms, refer to the [domain model](/boundary/docs/concepts/domain-model) section.
Please use the navigation to the left to learn more about a topic.
website/content/docs/concepts/security/index.mdx
-10
View File
@@ -1,10 +0,0 @@
---
layout: docs
page_title: Security
description: >-
Discover resources to help you understand Boundary's security.
---
# Security
This section describes Boundary's security norms. Here you can find in-depth analysis about how permissions, identity, and target security are handled within the Boundary product.
website/content/docs/concepts/transparent-sessions.mdx
+8 -20
View File
@@ -13,33 +13,21 @@ Transparent sessions shift Boundary from an active connection model to a passive
As long as Boundary authenticates a user and the user is authorized to access the target, Boundary intercepts the DNS call and routes traffic through a session automatically.
Transparent sessions require [aliases](/boundary/docs/concepts/aliases) and the [Boundary Client Agent](/boundary/docs/api-clients/client-agent).
Transparent sessions require aliases and the Boundary Client Agent.
An alias is a globally unique, DNS-like string that is associated with a destination resource. You can establish a session to a target by referencing its alias, instead of having to provide a target ID or target name and scope ID.
The Boundary Client Agent is Boundary's DNS daemon.
When the Boundary Client Agent runs alongside an authenticated Boundary client, the agent establishes itself as the primary resolver on the system and intercepts DNS requests.
The Boundary Desktop client facilitates quick target discovery and session establishment using your preferred client. If you configure aliases for your targets, install the Boundary Client Agent, and ensure you are authenticated to the cluster, connections are transparent to the user. Boundary provides OS notifications to make it clear when you connect to a target using a transparent session.
Boundary supports Windows and MacOS for transparent sessions.
Refer to the [Configure transparent sessions](/boundary/docs/configuration/target-aliases/transparent-sessions) page to get started.
## Known issues
Refer to the following table for known issues:
| Issue | Description |
| ----- | ----------- |
| SSH connection fails with man-in-the-middle warning | On Linux systems, the initial transparent session may be successful, but any subsequent connections prompt a warning that you may be experiencing a man-in-the-middle attack. <br /><br /> For more information, refer to [WARNING! Remote host indentification has changed! It is possible that someone is doing something nasty!](/boundary/docs/api-clients/client-agent#warning-remote-host-indentification-has-changed-it-is-possible-that-someone-is-doing-something-nasty) in the **Common error messages** section.|
| Boundary Client Agent authentication does not persist across restarts | When you reboot, you are required to re-authenticate to the Client Agent before you can use transparent sessions. |
| Windows installer prompts for restart | When you install Boundary, the Windows installer occasionally prompts you to restart your computer, however it is not necessary. |
| Boundary Client Agent resumes on reboot | If the Client Agent is paused and the machine is rebooted, the Client Agent will be resumed after the reboot. |
| Single-word aliases do not work on Windows | If you create an alias consisting of a single word without a dot (`.`), the alias will not work on Windows. |
| Windows installer does not support partial installations | The Windows installer fails to start the Client Agent if the Desktop client is not installed at the same time. |
| Alias connection failures inside containers/VMs | Using transparent sessions rely on network access to the local network of the computer the Client Agent is running on. Network enclaves such as those created by Docker containers and VMs cannot reach this network. |
| DNS lookup is broken on MacOS 15.1 and 15.2 | MacOS 15.1 and 15.2 may incorrectly block DNS lookups for the Client Agent. This issue is resolved in MacOS 15.3 and later. |
## More information
Refer to the following topics for more information:
- [Aliases](/boundary/docs/concepts/aliases)
- [Boundary Client Agent](/boundary/docs/api-clients/client-agent)
- [Configure transparent sessions](/boundary/docs/configuration/target-aliases/transparent-sessions)
- [Boundary Client Agent](/boundary/docs/client-agent)
- [Configure transparent sessions](/boundary/docs/targets/configuration/configure-transparent-sessions)
website/content/docs/concepts/workers.mdx
+35 -34
View File
@@ -26,40 +26,20 @@ You can use workers in various ways depending on your needs, as follows:
### Session proxying
You can use workers to proxy sessions between clients and targets located in public or private networks. In addition, you can configure workers in
[multi-hop](#multi-hop-sessions) sessions and form a chain of proxies to reach deeper into protected networks.
You can use workers to proxy sessions between clients and targets located in public or private networks. In addition, you can configure workers in multi-hop sessions and form a chain of proxies to reach deeper into protected networks.
### Worker authentication
Workers can [authenticate](/boundary/docs/concepts/security/connections-tls#pki-based-worker-authentication) directly to the control plane or through an upstream worker to the control plane. Authenticating through an upstream worker is also referred to as "multi-hop worker authentication."
Workers can authenticate directly to the control plane or through an upstream worker to the control plane. Authenticating through an upstream worker is also referred to as "multi-hop worker authentication."
### Controller proxy
In situations where controllers need access to a private service but don't have network access to it, workers can act as a proxy for communication. This is currently
supported for controllers connecting to a [private Vault](/boundary/tutorials/credential-management/hcp-private-vault-cred-injection)
environment.
In situations where controllers need access to a private service but don't have network access to it, workers can act as a proxy for communication. This is currently supported for controllers connecting to a private Vault environment.
### Protocol decryption
Workers can perform SSH protocol decryption for [credential injection](/boundary/docs/concepts/credential-management#credential-injection) and [session
recording](/boundary/docs/concepts/domain-model/session-recordings). For session recording, workers also write the recorded session contents directly to the [storage
bucket](/boundary/docs/concepts/domain-model/storage-buckets).
## Tags
In multi-datacenter and multi-cloud operating models, patterns of dividing up controllers, workers, and targets into appropriate regions or networks is often
desired to reduce latency or comply with security standards. You can assign workers [tags](/boundary/tutorials/worker-management/target-aware-workers) that Boundary
can [filter](/boundary/docs/concepts/filtering/worker-tags) through, to find the appropriate worker to use for a session. For example, Boundary could filter to workers
with tag “A,” to connect to targets in “Network A.”
![Boundary architecture example showing workers with tags](/img/worker-tags.png)
## Status and health
Boundary workers report their status to controllers on a regular basis. You can view the last time a worker reported its status in the
admin UI as **Last Seen** and in the CLI as the **Last Status Time**. If a worker hasn't reported status recently, it can be an
indication of an unhealthy worker.
You can query the worker health endpoint to determine the health of a worker. The endpoint returns the worker state, active
session count, and connection state of the worker. For more information, refer to the [health endpoints](/boundary/docs/operations/health) documentation.
Workers can perform SSH protocol decryption for credential injection and session recording. For session recording, workers also write the recorded session contents directly to the storage
bucket.
## Multi-hop sessions
@@ -69,14 +49,35 @@ Most organizations want to provide access to infrastructure without exposing pri
inbound traffic to route through multiple network enclaves in order to reach the target system.
Multi-hop sessions allow you to chain together two or more workers across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies.
Refer to the [multi-hop sessions](/boundary/docs/concepts/connection-workflows/multi-hop) documentation for more information.
## Tags
## Deployment
Workers are services that can run on a container or virtual machine. You should deploy them strategically within networks to provide access to targets. In
all editions of Boundary, workers are fully self-managed and can be deployed anywhere. In HCP Boundary, HCP-managed workers are automatically deployed with the cluster.
In multi-datacenter and multi-cloud operating models, patterns of dividing up controllers, workers, and targets into appropriate regions or networks is often
desired to reduce latency or comply with security standards. You can assign workers tags that Boundary
can filter through, to find the appropriate worker to use for a session. For example, Boundary could filter to workers with tag “A,” to connect to targets in “Network A.”
To learn more about workers and deployment, see:
* [Worker configuration](/boundary/docs/configuration/worker)
* [Recommended architecture](/boundary/docs/install-boundary/recommended-architecture)
* [Worker system requirements](/boundary/docs/install-boundary/system-requirements)
* [Worker management tutorials](/boundary/tutorials/worker-management)
![Boundary architecture example showing workers with tags](/img/worker-tags.png)
## Status and health
Boundary workers report their status to controllers on a regular basis. You can view the last time a worker reported its status in the admin UI as **Last Seen** and in the CLI as the **Last Status Time**. If a worker hasn't reported status recently, it can be an indication of an unhealthy worker.
You can query the worker health endpoint to determine the health of a worker. The endpoint returns the worker state, active session count, and connection state of the worker.
## Tutorial
Refer to the [HCP credential injection with private Vault](/boundary/tutorials/credential-management/hcp-private-vault-cred-injection) tutorial to practice configuring credential injection.
Refer to the [Worker-aware targets](/boundary/tutorials/worker-management/target-aware-workers) tutorial to practice configuring worker-aware targets and applying worker filters.
## More information
Refer to the following topics for more information:
- [TLS in Boundary](/boundary/docs/secure/encryption/connections-tls)
- [Credential injection](/boundary/docs/concepts/credential-management#credential-injection)
- [Session recording](/boundary/docs/session-recording)
- [Route traffic through a worker](/boundary/docs/workers/worker-tags)
- [Boundary health endpoints](/boundary/docs/monitor/health)
- [Multi-hop sessions](/boundary/docs/workers/multi-hop)
- [Filtering and listing resources](/boundary/docs/filtering)
website/content/docs/configuration/controller.mdx
+1 -1
View File
@@ -134,7 +134,7 @@ The `api_rate_limit` configuration stanza contains the following fields:
- `unlimited` - Indicates that the corresponding resources and actions should not be rate limited.
If you set this value to `true`, you should not specify values for the `limit` and `period` or you will receive an error.
For more information about how API rate limiting works, refer to the [API rate limiting](/boundary/docs/api-clients/api#rate-limiting) documentation.
For more information about how API rate limiting works, refer to the [API rate limiting](/boundary/docs/api/rate-limiting) documentation.
- `api_rate_limit_disable` - Disables API rate limiting, if set to `true`.
If `api_rate_limit_disable` is set to `true`, and you have provided any `api_rate_limit` stanzas, you will receive an error.
website/content/docs/configuration/events/common-sink-parameters.mdx
+22
View File
@@ -0,0 +1,22 @@
---
layout: docs
page_title: Common sink parameters
description: |-
The common sink parameters for all sink types.
---
# Common sink parameters
@include '/configuration-reference/events/common-sink-intro.mdx'
## `audit_config` parameters
@include '/configuration-reference/events/common-audit_config-parameters.mdx'
### `audit_filter_overrides` parameters
@include '/configuration-reference/events/common-audit_filter_overrides-parameters.mdx'
## `audit_config` examples
@include '/configuration-reference/events/common-audit_config-examples.mdx'
website/content/docs/configuration/events/common.mdx
-86
View File
@@ -1,86 +0,0 @@
---
layout: docs
page_title: Controller/worker - events - common sink parameters
description: |-
The common sink parameters for all sink types.
---
# Common sink parameters
These parameters are shared across all sink types:
- `name` - Specify a name for the sink.
- `description` - Specify a description for the sink.
- `event_types` - Specifies a list of event types that will be sent to the sink.
Can be `*`, `audit`, `error`, `observation`, `system`, or `telemetry`.
- `event_source_url` - Specifies an optional event source URL for the sink. If
not specified, the default source will be composed of the
`https://hashicorp.com/boundary.io/ServerName/Path/FileName`.
- `allow_filters` - Specifies a set of predicates for including an event in the
sink. If any filter matches, the event will be included. For more information,
on using filters see: [event filtering](/boundary/docs/concepts/filtering/events)
- `deny_filters` - Specifies a set predicates for excluding an event in the
sink. If any filter matches, the event will be excluded. For more information
on using filters see: [event filtering](/boundary/docs/concepts/filtering/events)
- `format` - Specifies the format for the sink. Can be `cloudevents-json`,
`cloudevents-text`, `hclog-json`, or `hclog-text`.
- `type` - Specifies the type of sink. Can be `stderr` or `file`.
- `audit_config` - Specifies configuration for the processing of audit events
for the sink. This is ignored if the sink is not configured to receive
`audit` events.
## `audit_config` parameters
- `audit_filter_overrides` - Specifies overrides for the filter operations that
are applied to audit events.
### `audit_filter_overrides` parameters
- `sensitive` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies
the filter operation to apply to fields that are classified as sensitive.
- `secret` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies
the filter operation to apply to fields that are classified as secret.
## `audit_config` examples
This example is equivalent to the default settings if no `audit_config` stanza
is provided.
```hcl
audit_config {
audit_filter_overrides {
sensitive = "redact"
secret = "redact"
}
}
```
This example will HMAC sensitive fields, and encrypt secrets.
```hcl
audit_config {
audit_filter_overrides {
sensitive = "hmac-sha256"
secret = "encrypt"
}
}
```
This example will not apply a filter to sensitive fields.
```hcl
audit_config {
audit_filter_overrides {
sensitive = ""
}
}
```
website/content/docs/configuration/events/file-sink.mdx
+18
View File
@@ -0,0 +1,18 @@
---
layout: docs
page_title: File sink - configuration reference
description: |-
The file sink configures Boundary to send events to a file.
---
# `file` sink
@include '/configuration-reference/events/file-sink-intro.mdx'
## Common parameters
These parameters are shared across all sink types: [common sink parameters](/boundary/docs/monitor/events/common)
## `file` parameters
@include '/configuration-reference/events/file-parameters.mdx'
website/content/docs/configuration/events/file.mdx
-47
View File
@@ -1,47 +0,0 @@
---
layout: docs
page_title: Controller/worker - events - file sink - configuration
description: |-
The file sink configures Boundary to send events to a file.
---
# `file` sink
The file sink configures Boundary to send events to a file.
```hcl
sink {
name = "obs-sink"
description = "Observations sent to a file"
event_types = ["observation"]
format = "cloudevents-json"
file {
path = "/var/log/boundary"
file_name = "events.ndjson"
}
}
```
The `sink` stanza may be specified more than once to make Boundary send events
to multiple sinks; however, each file sink must have a unique `path` +
`file_name`.
## Common parameters
These parameters are shared across all sink types: [common sink parameters](/boundary/docs/configuration/events/common)
## `file` parameters
These parameters are only valid for a `file` sink.
- `file_name` - Specifies the file name for the sink.
- `path` - Optionally specifies the file path for the sink.
- `rotate_bytes` - Optionally specifies the number of bytes that should trigger rotation of
a file sink.
- `rotate_duration` - Optionally specifies how often a file sink should be rotated.
- `rotate_max_files` - Optionally specifies how many historical rotated files should be kept
for a file sink.
website/content/docs/configuration/events/index.mdx
+4 -58
View File
@@ -1,68 +1,14 @@
---
layout: docs
page_title: Controller/worker - events
page_title: Events configuration reference
description: |-
The events stanza configures events-specific parameters.
Reference document for configuring event parameters
---
# `events` stanza
The `events` stanza configures Boundary events-specific parameters.
Example:
```hcl
events {
observations_enabled = true
sysevents_enabled = true
telemetry_enabled = false
sink "stderr" {
name = "all-events"
description = "All events sent to stderr"
event_types = ["*"]
format = "hclog-text"
}
sink {
name = "obs-sink"
description = "Observations sent to a file"
event_types = ["observation"]
format = "cloudevents-json"
file {
path = "/var/log/boundary"
file_name = "events.ndjson"
}
}
}
```
- `audit_enabled` - Specifies if audit events should be emitted.
- `observations_enabled` - Specifies if observation events should be emitted.
- `sysevents_enabled` - Specifies if system events should be emitted.
- `telemetry_enabled` - Specifies if telemetry events should be emitted.
To receive telemetry events, you must also set `observations_enabled` to `true`.
- `sink` - Specifies the configuration of an event sink. Currently, two types of
sink are supported: [file](/boundary/docs/configuration/events/file) and [stderr](/boundary/docs/configuration/events/stderr). If no sinks are configured then all
events will be sent to a default [stderr](/boundary/docs/configuration/events/stderr) sink. Events may be sent to multiple
sinks.
@include '/configuration-reference/events/events-stanza-intro.mdx'
## Default events stanza
If no event stanza is specified then the following default is used:
```hcl
events {
audit_enabled = false
observations_enabled = true
sysevents_enabled = true
telemetry_enabled = false
sink "stderr" {
name = "default"
event_types = ["*"]
format = "cloudevents-json"
}
}
```
@include '/configuration-reference/events/default-events-stanza.mdx'
website/content/docs/configuration/events/stderr-sink.mdx
+18
View File
@@ -0,0 +1,18 @@
---
layout: docs
page_title: stderr sink - configuration reference
description: |-
The stderr sink configures Boundary to send events to a stderr.
---
# `stderr` sink
@include '/configuration-reference/events/stderr-intro.mdx'
## Common parameters
These parameters are shared across all sink types: [common sink parameters](/boundary/docs/monitor/events/common)
## `stderr` parameters
@include '/configuration-reference/events/stderr-parameters.mdx'
website/content/docs/configuration/events/stderr.mdx
-28
View File
@@ -1,28 +0,0 @@
---
layout: docs
page_title: Controller - events - stderr sink - configuration
description: |-
The stderr sink configures Boundary to send events to a stderr.
---
# `stderr` sink
The stderr sink configures Boundary to send events to a stderr.
```hcl
sink "stderr" {
name = "all-events"
description = "All events sent to stderr"
event_types = ["*"]
format = "hclog-text"
}
```
## Common parameters
These parameters are shared across all sink types: [common sink parameters](/boundary/docs/configuration/events/common)
## `stderr` parameters
There are parameters are only valid for a `stderr` sink.
website/content/docs/configuration/index.mdx
+6 -6
View File
@@ -5,11 +5,11 @@ description: >-
Learn about the parameters that make up the Boundary HCL configuration file. View parameters for HCP and self-managed installations.
---
# Configuration
# Top-level configuration parameters
[listener]: /boundary/docs/configuration/listener
[controller]: /boundary/docs/configuration/controller
[worker]: /boundary/docs/configuration/worker
[worker]: /boundary/docs/configuration/workers
[kms]: /boundary/docs/configuration/kms
[plugins]: /boundary/docs/configuration/plugins
[events]: /boundary/docs/configuration/events
@@ -30,7 +30,7 @@ path to the file.
## Shared self-managed and HCP Boundary parameters
- [`worker`](/boundary/docs/configuration/worker): Worker specific configuration. If
- [`worker`](/boundary/docs/configuration/workers): Worker specific configuration. If
present, `boundary server` will start a Worker subprocess.
- [`listener`](/boundary/docs/configuration/listener): Configures the listeners on which
@@ -45,7 +45,7 @@ path to the file.
where Boundary's operational endpoints live (eg: /health).
- [`kms`](/boundary/docs/configuration/kms): Configures KMS blocks [for various
purposes](/boundary/docs/concepts/security/data-encryption).
purposes](/boundary/docs/secure/encryption/data-encryption).
- [`events`](/boundary/docs/configuration/events): Configures event (observability,
audit, error) handling.
@@ -93,7 +93,7 @@ path to the file.
The `SIGHUP` signal causes worker and controller processes to reload their configuration files to pick up updated values.
~> **Note:** You cannot reload all configuration values using the `SIGHUP` signal. Refer to the configuration pages for
[workers](/boundary/docs/configuration/worker/) and [controllers](/boundary/docs/configuration/controller) for details
[workers](/boundary/docs/configuration/workers) and [controllers](/boundary/docs/configuration/controller) for details
on which values can be reloaded on `SIGHUP`.
The `SIGTERM` and `SIGINT` signals cause worker and controller processes to enter graceful shutdown. A graceful shutdown for a controller closes listeners and servers before shutting down the controller. A graceful shutdown for a worker waits for any sessions to drain
@@ -103,4 +103,4 @@ before shutting down the worker. Workers in a graceful shutdown state do not rec
For complete example configurations see the sections for
[controller](/boundary/docs/configuration/controller) and
[worker](/boundary/docs/configuration/worker).
[worker](/boundary/docs/configuration/workers).
website/content/docs/configuration/kms/awskms.mdx
+6 -6
View File
@@ -32,7 +32,7 @@ These parameters apply to the `kms` stanza in the Boundary configuration file:
- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `worker-auth-storage`,
`root`, `previous-root`, `recovery`, `bsr`, or `config`.
To [enable session recording](/boundary/docs/configuration/session-recording/enable-session-recording), you must configure the `bsr` value for the `purpose`.
To [enable session recording](/boundary/docs/session-recording/configuration/enable-session-recording), you must configure the `bsr` value for the `purpose`.
- `region` `(string: "us-east-1")`: The AWS region where the encryption key
lives. If not provided, may be populated from the `AWS_REGION` or
@@ -54,22 +54,22 @@ These parameters apply to the `kms` stanza in the Boundary configuration file:
also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
part of the AWS profile from the AWS CLI or instance profile.
- `shared_creds_filename` `(string: "")`: (Boundary 0.5.1+) If set, the file
- `shared_creds_filename` `(string: "")`: If set, the file
name to read as a shared credentials file.
- `shared_creds_profile` `(string: "")`: (Boundary 0.5.1+) If set, the
- `shared_creds_profile` `(string: "")`: If set, the
profile to use from the shared credentials file. If not set, will use the
`AWS_PROFILE` env var, or if that is not set, `"default"`.
- `role_arn` `(string: "")`: (Boundary 0.5.1+) If this and
- `role_arn` `(string: "")`: If this and
`web_identity_token_file` are set, the role ARN to use when using a web
identity role provider with STS.
- `web_identity_token_file` `(string: "")`: (Boundary 0.5.1+) If this and
- `web_identity_token_file` `(string: "")`: If this and
`role_arn` are set, the token file to use when using a web identity role
provider with STS.
- `role_session_name` `(string: "")`: (Boundary 0.5.1+) If using the web
- `role_session_name` `(string: "")`: If using the web
identity role provider, the role session to use.
- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS
website/content/docs/configuration/kms/index.mdx
+12 -2
View File
@@ -9,8 +9,6 @@ description: >-
The `kms` stanza configures Boundary kms-specific parameters.
For more examples, please choose a specific KMS technology from the sidebar.
## Configuration
KMS configuration can be done through the Boundary configuration file using the
@@ -29,3 +27,15 @@ kms "transit" {
# ...
}
```
## More information
For specific KMS examples, refer to the following topics:
- [aead KMS](/boundary/docs/configuration/kms/aead)
- [AliCloud KMS](/boundary/docs/configuration/kms/alicloudkms)
- [AWS KMS](/boundary/docs/configuration/kms/awskms)
- [Azure Key Vault KMS](/boundary/docs/configuration/kms/azurekeyvault)
- [GCP Cloud KMS](/boundary/docs/configuration/kms/gcpckms)
- [OCI KMS](/boundary/docs/configuration/kms/ocikms)
- [Vault Transit KMS](/boundary/docs/configuration/kms/transit)
website/content/docs/configuration/listener/tcp.mdx
-345
View File
@@ -1,345 +0,0 @@
---
layout: docs
page_title: TCP listener configuration
description: >-
Learn about using the TCP listener on a TCP address and port, and view configurable parameters. Understand custom response headers. View example configurations.
---
# `tcp` listener
The TCP listener configures Boundary to listen on a TCP address/port.
```hcl
listener "tcp" {
purpose = "api"
address = "127.0.0.1:9200"
}
```
The `listener` stanza may be specified more than once to make Boundary listen on
multiple interfaces; however, only one listener marked for `cluster` purpose is
allowed.
## Listener's custom response headers
Boundary supports defining custom HTTP response headers for all requests on any Boundary controller.
Headers are defined based on the returned status code. For example, you can define a list of
custom response headers for the `200` status code, and another list of custom response headers for
the `307` status code, and so on. You can also define headers based on the hundred-level status
code. For example, a list of headers applied to the `4xx` code will be applied to 400, 401, 404, and
all other 400-level status codes. The more specific the status, the higher priority it has.
Default headers are overwritten by hundred-level headers, which are overwritten by status-specific
headers.
There are two different config parameters that define headers: `custom_api_response_headers` and
`custom_ui_response_headers`. API headers apply to API endpoints, currently all paths starting
with `/v1/`. UI headers apply to all other paths. This allows for configuring headers specifically
for serving content to a web browser, such as CSP headers.
## `tcp` listener parameters
Refer to the following sections for `tcp` listener parameters.
### General
- `purpose` `(string: "")` - Specifies the purpose. Can be `api`, `cluster`,
`proxy`, or `ops`.
- `address` `(string: "127.0.0.1:9200")` – Specifies the address to bind to for
listening.
- `http_idle_timeout` `(string: "5m")` - Specifies the maximum amount of time to
wait for the next request when keep-alives are enabled. If `http_idle_timeout`
is zero, the value of `http_read_timeout` is used. If both are zero, the value
of `http_read_header_timeout` is used. This is specified using a label suffix
like `"30s"` or `"1h"`.
- `http_read_header_timeout` `(string: "10s")` - Specifies the amount of time
allowed to read request headers. This is specified using a label suffix like
`"30s"` or `"1h"`.
- `http_read_timeout` `(string: "30s")` - Specifies the maximum duration for
reading the entire request, including the body. This is specified using a
label suffix like `"30s"` or `"1h"`.
- `http_write_timeout` `(string: "0")` - Specifies the maximum duration before
timing out writes of the response and is reset whenever a new request's header
is read. The default value of `"0"` means infinity. This is specified using a
label suffix like `"30s"` or `"1h"`.
<!-- We don't have this implemented yet
- `max_request_size` `(int: 33554432)` – Specifies a hard maximum allowed
request size, in bytes. Defaults to 32 MB. Specifying a number less than or
equal to `0` turns off limiting altogether.
!-->
- `max_request_duration` `(string: "90s")` – Specifies the maximum
request duration allowed before Boundary cancels the request. This overrides
`default_max_request_duration` for this listener.
- `cors_enabled` `(boolean: true)` - Specifies if CORS should be enabled, which
allows Boundary to support external browser-based clients (not including admin
UI), such as Boundary Desktop. If not specified, CORS will be enabled with an
allowed origin that grants access to Boundary Desktop, unless overridden with
`cors_disable_default_allowed_origin_values`.
- `cors_disable_default_allowed_origin_values` `(boolean: false)` - Specifies
that Boundary should not append default allowed origin values to any specified
in `cors_allowed_origins`, such as Boundary Desktop's origin. This also
disables the behavior of enabling CORS if `cors_enabled` is not specified.
- `cors_allowed_origins` `(array(string): ["serve://boundary"])` - An array of
allowed CORS origins. Origins must include protocol, host, and port (if port
is different than the default for the specified protocol). To allow all
origins, set to `['*']`. By default, Boundary Desktop's origin
`serve://boundary` is appended to any values included here, unless
`cors_disable_default_allowed_origin_values` is specified.
- `cors_allowed_headers` `(array(string): [])` – An array specifying headers
that are permitted to be on cross-origin requests. Headers set via this
parameter will be appended to the list of headers that Boundary allows by
default, such as `"Content-Type"`, `"X-Requested-With"`, and
`"Authorization"`.
### `custom_api_response_headers` parameters
- `default` `(key-value-map: {})` - A map of string header names to an array of
string values. The default headers are set on all endpoints regardless of
the status code value. For an example, refer to the
[Configuring custom http response headers](#configuring-custom-http-response-headers)
section.
- `<collective status code>` `(key-value-map: {})` - A map of string header names
to an array of string values. These headers are set only when the response status
code falls under the collective status code.
For example, `"2xx" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
is set when the http response status code is `"200"`, `"204"`, etc. This overrides
headers defined at the `default` level.
- `<specific status code>` `(key-value-map: {})` - A map of string header names
to an array of string values. These headers are set only when the specific status
code is returned. For example, `"200" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
is set when the http response status code is `"200"`. This overrides headers defined at
the `default` and `collective status code` level.
### `custom_ui_response_headers` parameters
- `default` `(key-value-map: {})` - A map of string header names to an array of
string values. The default headers are set on all endpoints regardless of
the status code value. For an example, refer to the
[Configuring custom http response headers](#configuring-custom-http-response-headers)
section.
- `<collective status code>` `(key-value-map: {})` - A map of string header names
to an array of string values. These headers are set only when the response status
code falls under the collective status code.
For example, `"2xx" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
is set when the http response status code is `"200"`, `"204"`, etc. This overrides
headers defined at the `default` level.
- `<specific status code>` `(key-value-map: {})` - A map of string header names
to an array of string values. These headers are set only when the specific status
code is returned. For example, `"200" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
is set when the http response status code is `"200"`. This overrides headers defined at
the `default` and `collective status code` level.
### TLS
~> `tls` parameters are valid for `api` and `ops` listeners. `cluster`
and `proxy` connections use their own ephemeral TLS stacks. For more
information, see [the connections security concepts
page](/boundary/docs/concepts/security/connections-tls).
- `tls_disable` `(string: "false")` – Specifies if TLS will be disabled. Boundary
assumes TLS by default, so you must explicitly disable TLS to opt-in to
insecure communication.
- `tls_cert_file` `(string: <required-if-enabled, reloads-on-SIGHUP>)` –
Specifies the path to the certificate for TLS. To configure the listener to
use a CA certificate, concatenate the primary certificate and the CA
certificate together. The primary certificate should appear first in the
combined file. On `SIGHUP`, the path set here _at Boundary startup_ will be
used for reloading the certificate; modifying this value while Boundary is
running will have no effect for `SIGHUP`s.
- `tls_key_file` `(string: <required-if-enabled, reloads-on-SIGHUP>)` –
Specifies the path to the private key for the certificate. If the key file is
encrypted, you will be prompted to enter the passphrase on server startup. The
passphrase must stay the same between key files when reloading your
configuration using `SIGHUP`. On `SIGHUP`, the path set here _at Boundary
startup_ will be used for reloading the certificate; modifying this value
while Boundary is running will have no effect for `SIGHUP`s.
- `tls_min_version` `(string: "tls12")` – Specifies the minimum supported
version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".
!> TLS 1.1 and lower are generally considered insecure.
- `tls_max_version` `(string: "tls13")` – Specifies the maximum supported
version of TLS, useful if appliances (e.g. load balancers) are not yet capable
of higher levels. Accepted values are "tls10", "tls11", "tls12" or "tls13".
!> TLS 1.1 and lower are generally considered insecure.
- `tls_cipher_suites` `(string: "")` – Override the default list of supported
ciphersuites (which varies by TLS version) with the the specified
comma-delimited list. The list of all available ciphersuites is available in
the [Golang TLS documentation][golang-tls].
- `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the
server's ciphersuite over the client ciphersuites.
- `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client
authentication for this listener; the listener will require a presented
client cert that successfully validates against system CAs.
- `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file
used for checking the authenticity of client.
<!-- Not enabled yet
- `x_forwarded_for_authorized_addrs` `(string: <required-to-enable>)` –
Specifies the list of source IP CIDRs for which an X-Forwarded-For header
will be trusted. Comma-separated list or JSON array. This turns on
X-Forwarded-For support.
- `x_forwarded_for_hop_skips` `(string: "0")` – The number of addresses that will be
skipped from the _rear_ of the set of hops. For instance, for a header value
of `1.2.3.4, 2.3.4.5, 3.4.5.6`, if this value is set to `"1"`, the address that
will be used as the originating client IP is `2.3.4.5`.
- `x_forwarded_for_reject_not_authorized` `(string: "true")` – If set false,
if there is an X-Forwarded-For header in a connection from an unauthorized
address, the header will be ignored and the client connection used as-is,
rather than the client connection rejected.
- `x_forwarded_for_reject_not_present` `(string: "true")` – If set false, if
there is no X-Forwarded-For header or it is empty, the client address will be
used as-is, rather than the client connection rejected.
### `telemetry` parameters
- `unauthenticated_metrics_access` `(string: "false")` - If set to true, allows
unauthenticated access to the `/v1/sys/metrics` endpoint.
!-->
## `tcp` listener examples
Refer to the following sections for examples of `tcp` listeners.
### Configure TLS
This example shows enabling a TLS listener.
```hcl
listener "tcp" {
purpose = "api"
tls_cert_file = "/etc/certs/Boundary.crt"
tls_key_file = "/etc/certs/Boundary.key"
}
```
### Configure custom http response headers
This example shows configuring custom http response headers. Operators can configure
`"custom_api_response_headers"` and `"custom_ui_response_headers"` sub-stanzas in the listener stanza to
set custom http headers that are appropriate to their applications. Examples of such headers are
`"Strict-Transport-Security"` and `"Content-Security-Policy"` which are known HTTP headers, and could be
configured to harden the security of an application communicating with the Boundary endpoints. Note that
vulnerability scans often examine such security related HTTP headers. In addition, you can configure
application-specific custom headers. For example, `"X-Custom-Header"` has been configured in the example
below.
```hcl
listener "tcp" {
custom_api_response_headers {
"default" = {
"Strict-Transport-Security" = ["max-age=31536000; includeSubDomains"],
"X-Custom-Header" = ["Custom Header Default Value"],
},
"2xx" = {
"X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
},
"301" = {
"Strict-Transport-Security" = ["max-age=31536000"],
},
}
custom_ui_response_headers {
"default" = {
"Strict-Transport-Security" = ["max-age=31536000; includeSubDomains"],
"Content-Security-Policy" = ["default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; frame-src 'self'; font-src 'self'; connect-src 'self'; img-src 'self' data:; style-src 'self'; media-src 'self'; manifest-src 'self'; style-src-attr 'self'; frame-ancestors 'self'"],
"X-Custom-Header" = ["Custom Header Default Value"],
},
"2xx" = {
"X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
},
"301" = {
"Strict-Transport-Security" = ["max-age=31536000"],
"Content-Security-Policy" = ["default-src 'none'; script-src 'none'; connect-src 'none'"],
},
}
}
```
Note that Boundary requires `script-src 'wasm-unsafe-eval'` for playback of session recordings.
In situations where a header is defined under several status code subsections,
Boundary returns the header matching the most specific response code. For example,
with the config example below, a `307` response would return `307 Custom header value`,
while a `306` would return `3xx Custom header value`.
```hcl
listener "tcp" {
custom_api_response_headers {
"default" = {
"X-Custom-Header" = ["default Custom header value"]
},
"3xx" = {
"X-Custom-Header" = ["3xx Custom header value"]
},
"307" = {
"X-Custom-Header" = ["307 Custom header value"]
}
}
}
```
There may also be situations where default or collective status headers have been defined,
but you do not want them returned for a specific status code. You can unset headers at any
level by defining the headers as an empty list.
```hcl
listener "tcp" {
custom_api_response_headers {
"default" = {
"X-Custom-Header" = ["default Custom header value"]
},
"3xx" = {
"X-Custom-Header" = ["3xx Custom header value"]
},
"307" = {
// Do not return this header for 307 responses
"X-Custom-Header" = []
}
}
}
```
### Listen on mulitple interfaces
This example shows Boundary listening on a private interface, as well as localhost.
```hcl
listener "tcp" {
purpose = "api"
address = "127.0.0.1:9200"
}
listener "tcp" {
purpose = "cluster"
address = "10.0.0.5:9201"
}
```
[golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go
[api-addr]: /boundary/docs/configuration#api_addr
[cluster-addr]: /boundary/docs/configuration#cluster_addr
website/content/docs/configuration/listener/unix.mdx
-204
View File
@@ -1,204 +0,0 @@
---
layout: docs
page_title: Unix domain socket listener configuration
description: >-
Learn about using the Unix listener on a specified Unix domain socket, and view configurable parameters. View example Unix listener configurations.
---
# `unix` listener
The `unix` listener configures Boundary to listen on a Unix domain socket.
~> **Note:** This is only available for listeners for `api` and `cluster` purpose.
Unix sockets cannot currently be used for `"proxy"` purpose on a Worker.
```hcl
listener "unix" {
purpose = "api"
address = "/var/run/boundary-api.sock"
}
```
The `listener` stanza may be specified more than once to make Boundary listen on
multiple interfaces; however, only one listener marked for `cluster` purpose is
allowed.
## `unix` listener parameters
Refer to the following sections for the supported `unix` listener parameters.
### General
- `purpose` `(string: "")` - Specifies the purpose. Can be `api`, `ops` or `cluster`.
- `address` `(string: "")` – Specifies the address (filesystem path) to bind to
for listening.
- `http_idle_timeout` `(string: "5m")` - Specifies the maximum amount of time to
wait for the next request when keep-alives are enabled. If `http_idle_timeout`
is zero, the value of `http_read_timeout` is used. If both are zero, the value
of `http_read_header_timeout` is used. This is specified using a label suffix
like `"30s"` or `"1h"`.
- `http_read_header_timeout` `(string: "10s")` - Specifies the amount of time
allowed to read request headers. This is specified using a label suffix like
`"30s"` or `"1h"`.
- `http_read_timeout` `(string: "30s")` - Specifies the maximum duration for
reading the entire request, including the body. This is specified using a
label suffix like `"30s"` or `"1h"`.
- `http_write_timeout` `(string: "0")` - Specifies the maximum duration before
timing out writes of the response and is reset whenever a new request's header
is read. The default value of `"0"` means infinity. This is specified using a
label suffix like `"30s"` or `"1h"`.
<!-- We don't have this implemented yet
- `max_request_size` `(int: 33554432)` – Specifies a hard maximum allowed
request size, in bytes. Defaults to 32 MB. Specifying a number less than or
equal to `0` turns off limiting altogether.
!-->
- `max_request_duration` `(string: "90s")` – Specifies the maximum
request duration allowed before Boundary cancels the request. This overrides
`default_max_request_duration` for this listener.
- `cors_enabled` `(boolean: true)` - Specifies if CORS should be enabled, which
allows Boundary to support external browser-based clients (not including admin
UI), such as Boundary Desktop. If not specified, CORS will be enabled with an
allowed origin that grants access to Boundary Desktop, unless overridden with
`cors_disable_default_allowed_origin_values`.
- `cors_disable_default_allowed_origin_values` `(boolean: false)` - Specifies
that Boundary should not append default allowed origin values to any specified
in `cors_allowed_origins`, such as Boundary Desktop's origin. This also
disables the behavior of enabling CORS if `cors_enabled` is not specified.
- `cors_allowed_origins` `(array(string): ["serve://boundary"])` - An array of
allowed CORS origins. Origins must include protocol, host, and port (if port
is different than the default for the specified protocol). To allow all
origins, set to `['*']`. By default, Boundary Desktop's origin
`serve://boundary` is appended to any values included here, unless
`cors_disable_default_allowed_origin_values` is specified.
- `cors_allowed_headers` `(array(string): [])` – An array specifying headers
that are permitted to be on cross-origin requests. Headers set via this
parameter will be appended to the list of headers that Boundary allows by
default, such as `"Content-Type"`, `"X-Requested-With"`, and
`"Authorization"`.
### TLS
~> `tls` parameters are valid for `api` and `ops` listeners. `cluster`
and `proxy` connections use their own ephemeral TLS stacks. For more
information, see [the connections security concepts
page](/boundary/docs/concepts/security/connections-tls).
- `tls_disable` `(string: "false")` – Specifies if TLS will be disabled. Boundary
assumes TLS by default, so you must explicitly disable TLS to opt-in to
insecure communication.
- `tls_cert_file` `(string: <required-if-enabled, reloads-on-SIGHUP>)` –
Specifies the path to the certificate for TLS. To configure the listener to
use a CA certificate, concatenate the primary certificate and the CA
certificate together. The primary certificate should appear first in the
combined file. On `SIGHUP`, the path set here _at Boundary startup_ will be
used for reloading the certificate; modifying this value while Boundary is
running will have no effect for `SIGHUP`s.
- `tls_key_file` `(string: <required-if-enabled, reloads-on-SIGHUP>)` –
Specifies the path to the private key for the certificate. If the key file is
encrypted, you will be prompted to enter the passphrase on server startup. The
passphrase must stay the same between key files when reloading your
configuration using `SIGHUP`. On `SIGHUP`, the path set here _at Boundary
startup_ will be used for reloading the certificate; modifying this value
while Boundary is running will have no effect for `SIGHUP`s.
- `tls_min_version` `(string: "tls12")` – Specifies the minimum supported
version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".
!> TLS 1.1 and lower are generally considered insecure.
- `tls_max_version` `(string: "tls13")` – Specifies the maximum supported
version of TLS, useful if appliances (e.g. load balancers) are not yet capable
of higher levels. Accepted values are "tls10", "tls11", "tls12" or "tls13".
!> TLS 1.1 and lower are generally considered insecure.
- `tls_cipher_suites` `(string: "")` – Override the default list of supported
ciphersuites (which varies by TLS version) with the the specified
comma-delimited list. The list of all available ciphersuites is available in
the [Golang TLS documentation][golang-tls].
- `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the
server's ciphersuite over the client ciphersuites.
- `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client
authentication for this listener; the listener will require a presented
client cert that successfully validates against system CAs.
- `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file
used for checking the authenticity of client.
<!-- Not enabled yet
- `x_forwarded_for_authorized_addrs` `(string: <required-to-enable>)` –
Specifies the list of source IP CIDRs for which an X-Forwarded-For header
will be trusted. Comma-separated list or JSON array. This turns on
X-Forwarded-For support.
- `x_forwarded_for_hop_skips` `(string: "0")` – The number of addresses that will be
skipped from the _rear_ of the set of hops. For instance, for a header value
of `1.2.3.4, 2.3.4.5, 3.4.5.6`, if this value is set to `"1"`, the address that
will be used as the originating client IP is `2.3.4.5`.
- `x_forwarded_for_reject_not_authorized` `(string: "true")` – If set false,
if there is an X-Forwarded-For header in a connection from an unauthorized
address, the header will be ignored and the client connection used as-is,
rather than the client connection rejected.
- `x_forwarded_for_reject_not_present` `(string: "true")` – If set false, if
there is no X-Forwarded-For header or it is empty, the client address will be
used as-is, rather than the client connection rejected.
### `telemetry` parameters
- `unauthenticated_metrics_access` `(string: "false")` - If set to true, allows
unauthenticated access to the `/v1/sys/metrics` endpoint.
!-->
## `unix` listener examples
Refer to the following sections for examples of `unix` listeners.
### Configure TLS
This example shows enabling a TLS listener.
```hcl
listener "unix" {
purpose = "api"
address = "/var/run/boundary-api.sock"
tls_cert_file = "/etc/certs/Boundary.crt"
tls_key_file = "/etc/certs/Boundary.key"
}
```
### Listen on multiple interfaces
This example shows Boundary listening on a private interface, as well as localhost.
```hcl
listener "tcp" {
purpose = "api"
address = "/var/run/boundary-api.sock"
}
listener "tcp" {
purpose = "cluster"
address = "/var/run/boundary-cluster.sock"
}
```
[golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go
[api-addr]: /boundary/docs/configuration#api_addr
[cluster-addr]: /boundary/docs/configuration#cluster_addr
website/content/docs/configuration/listeners/index.mdx
+17
View File
@@ -0,0 +1,17 @@
---
layout: docs
page_title: Listeners - configuration reference
description: >-
The listener stanza configures the addresses and ports on which Boundary will respond to requests.
---
# `listener` stanza
The `listener` stanza configures the addresses and ports on which Boundary will
respond to requests. At this time, there are two listener types:
[TCP](/boundary/docs/configuration/listeners/tcp-listeners) and [Unix](/boundary/docs/configuration/listeners/unix-listeners).
## `listener` purpose
@include '/configuration-reference/listeners/listener-purpose.mdx'
website/content/docs/configuration/listeners/tcp-listeners.mdx
+55
View File
@@ -0,0 +1,55 @@
---
layout: docs
page_title: TCP listeners - configuration reference
description: >-
Learn about using the TCP listener on a TCP address and port, and view configurable parameters. Understand custom response headers. View example configurations.
---
# `tcp` listener
@include '/configuration-reference/listeners/tcp-intro.mdx'
## Listener's custom response headers
@include '/configuration-reference/listeners/tcp-custom-response-headers.mdx'
## `tcp` listener parameters
Refer to the following sections for `tcp` listener parameters.
### General
@include '/configuration-reference/listeners/tcp-general-parameters.mdx'
### `custom_api_response_headers` parameters
@include '/configuration-reference/listeners/tcp-custom-api-response-headers.mdx'
### `custom_ui_response_headers` parameters
@include '/configuration-reference/listeners/tcp-custom-ui-response-headers.mdx'
### TLS
@include '/configuration-reference/listeners/tcp-tls.mdx'
<!-- Not enabled yet
### `telemetry` parameters
@include '/configuration-reference/listeners/tcp-telemetry.mdx' !-->
## `tcp` listener examples
Refer to the following sections for examples of `tcp` listeners.
### Configure TLS
@include '/configuration-reference/listeners/tcp-configure-tls.mdx'
### Configure custom http response headers
@include '/configuration-reference/listeners/tcp-configure-custom-http-response-headers.mdx'
### Listen on mulitple interfaces
@include '/configuration-reference/listeners/tcp-listen-on-mulitple-interfaces.mdx'
website/content/docs/configuration/listeners/unix-listeners.mdx
+45
View File
@@ -0,0 +1,45 @@
---
layout: docs
page_title: Unix domain socket - listeners - configuration reference
description: >-
Learn about using the Unix listener on a specified Unix domain socket, and view configurable parameters. View example Unix listener configurations.
---
# `unix` listener
@include '/configuration-reference/listeners/unix-intro.mdx'
## `unix` listener parameters
Refer to the following sections for the supported `unix` listener parameters.
### General
@include '/configuration-reference/listeners/unix-general-parameters.mdx'
### TLS
@include '/configuration-reference/listeners/unix-tls-parameters.mdx'
<!-- Not enabled yet
### `telemetry` parameters
@include '/configuration-reference/listeners/unix-telemetry.mdx'
!-->
## `unix` listener examples
Refer to the following sections for examples of `unix` listeners.
### Configure TLS
@include '/configuration-reference/listeners/unix-configure-tls.mdx'
### Listen on multiple interfaces
@include '/configuration-reference/listeners/unix-listen-on-multiple-interfaces.mdx'
[golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go
[api-addr]: /boundary/docs/configuration#api_addr
[cluster-addr]: /boundary/docs/configuration#cluster_addr
website/content/docs/configuration/plugins.mdx
+2 -4
View File
@@ -7,10 +7,8 @@ description: >-
# `plugin` stanza
The `plugin` stanza configures plugin-specific parameters. The plugin system was
introduced in Boundary 0.7.0 and is currently internal; over time, the intent is
to provide a mechanism for third-party plugins to be able to be used. Available
plugins are currently bundled with Boundary and executed automatically.
The `plugin` stanza configures plugin-specific parameters. The plugin system is currently internal; over time, the intent is to provide a mechanism for third-party plugins to be able to be used.
Available plugins are currently bundled with Boundary and executed automatically.
There is currently one configuration parameter available:
website/content/docs/configuration/session-recording/index.mdx
-60
View File
@@ -1,60 +0,0 @@
---
layout: docs
page_title: Session recording overview
description: >-
Learn about using session recording to audit user sessions for compliance and threat management. Understand considerations for local and remote storage.
---
# Overview
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary Plus or Boundary Enterprise</a></EnterpriseAlert>
Boundary provides auditing capabilities using a feature called session recording.
In Boundary, a session represents a set of connections between a user and a host from a target. The session begins when an authorized user requests access to a target, and it ends when that access is terminated.
When you enable session recording on a target, a worker records any sessions that access that target. The worker stores the session recording on local disk during the recording phase, and then moves the recording to the external object store when the session is terminated.
Session recordings are stored in the [BSR (Boundary Session Recording)](/boundary/docs/concepts/auditing/#bsr-directory-structure) format. Any credentials needed to access the external object store are passed from the controller to the recording worker when the session is established.
You can view the recordings later with a session player that runs in a web browser.
## Storage considerations
The BSR captures all the data transmitted between a user and a target during a single session. As a result, the size of a BSR is dependent on user activity. At a minimum, a BSR for a session with one connection requires 8KB of space for its file for BSR keys, checksums, and metadata.
Determining how much storage you need to allocate on workers and the external storage provider for recordings depends on user activity, but the following two examples are provided to help with storage estimates:
- For one minute of simple shell activity, a BSR can be around 20KB in size. The storage requirements for 1,000 such sessions would be 20MB.
- Sending 50MB of data results in a BSR around 50.1MB in size. The storage requirements for 1,000 such sessions would be 50.1 GB.
When you estimate worker storage requirements, consider the number of concurrent sessions that will be recorded on that worker. Boundary writes the BSR to the worker's local storage while the session is active, and then moves it to the remote storage bucket when the session is closed.
When you estimate storage requirements for the external storage provider, consider your [storage policy](/boundary/docs/concepts/domain-model/storage-policy) and how long a BSR will be retained in the external storage bucket.
<Warning>
Boundary supports recorded session files up to 5 GB in size.
If a recorded session file is over 5 GB, the session details show the recording state as `Failed` and you may not be able to play back the session.
Be careful when you use Secure File Copy (SCP) to transfer large files during a recorded session because it can result in large recorded session files.
</Warning>
## Enable session recording
To enable session recording, you must:
1. [Configure workers for local storage](/boundary/docs/configuration/session-recording/configure-worker-storage)
1. Configure an external storage provider:
- [Amazon S3](/boundary/docs/configuration/session-recording/storage-providers/configure-s3)
- [MinIO](/boundary/docs/configuration/session-recording/storage-providers/configure-minio)
- [S3-compliant](/boundary/docs/configuration/session-recording/storage-providers/configure-s3-compliant)
1. [Create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket)
1. [Enable session recording on a target](/boundary/docs/configuration/session-recording/enable-session-recording)
## Configure recording retention policies
After enabling session recording, you can configure retention policies for recorded sessions:
1. [Configure storage policies](/boundary/docs/configuration/session-recording/configure-storage-policy)
1. [Update storage policies](/boundary/docs/configuration/session-recording/update-storage-policy)
website/content/docs/configuration/target-aliases/index.mdx
-35
View File
@@ -1,35 +0,0 @@
---
layout: docs
page_title: Overview
description: >-
Learn how to configure aliases and transparent sessions to enhance end-user workflows and simplify target access.
---
# Overview
Target aliases simplify the connection workflow for end users by allowing them to reference targets using a globally unique DNS-like string.
Without aliases, connecting to an end target requires you to reference the target ID, or a combination of target name and scope:
```shell-session
$ boundary connect ssh -target-id ttcp_1234567890
```
```shell-session
$ boundary connect ssh -target-name sql-database -target-scope-name -staging
```
With target aliases, a single globally referenced value is assigned to a target, simplifying connection workflows and enabling transparent sessions for Enterprise and HCP end users.
```shell-session
$ boundary connect ssh sql-database-staging
```
## Configure target aliases
To set up a target alias:
1. [Create a target alias](/boundary/docs/configuration/target-aliases/create-target-alias)
1. [Connect to a target using an alias](/boundary/docs/configuration/target-aliases/connect-target-alias)
After you set up a target alias, you can optionally [Configure transparent sessions for end users](/boundary/docs/configuration/target-aliases/transparent-sessions). <sup>HCP/ENT</sup>
website/content/docs/configuration/target-aliases/transparent-sessions.mdx
-119
View File
@@ -1,119 +0,0 @@
---
layout: docs
page_title: Configure transparent sessions
description: >-
Learn how to configure transparent sessions to enhance end-user workflows and simplify target access.
---
# Configure transparent sessions
@include 'alerts/enterprise-only.mdx'
## Requirements
Before you configure transparent sessions, you must:
- If you have previous versions of the Boundary Desktop or CLI client in your local environment, ensure that they are fully uninstalled before you install with the latest Boundary installer.
- Download the appropriate Boundary installer for your Windows or MacOS environment from the [Install Boundary](/boundary/install#installer) page or the [releases](https://releases.hashicorp.com/boundary-installer) page.
- Ensure that both IPv4 and IPv6 protocols are enabled for your environment. The [Client Agent](/boundary/docs/api-clients/client-agent) requires both protocols to start and perform DNS lookups.
Once Boundary is installed, you should make sure you have the appropriate grants configured so that you can resolve aliases and establish transparent sessions.
For more information, refer to the [Grants](/boundary/docs/api-clients/client-agent#grants) section in the Client Agent documentation.
<Warning>
A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases.
Clusters created before April 26, 2025 may be missing the following grants:
`ids={{.User.Id}};type=user;actions=list-resolvable-aliases`
`ids=*;type=target;actions=list,read`
If your cluster is missing these grants, HashiCorp recommends adding them.
For more information, refer to the [known issue](/boundary/docs/release-notes/v0_19_0#hcp-grants).
</Warning>
## Install the Boundary clients
Complete the following steps to install the Boundary Client Agent, CLI, and Desktop client:
1. Install Boundary using the installer.
Make sure to select the options **Boundary Client Agent**, **CLI**, and **Desktop**.
1. Open the CLI and type the following command to confirm that the version is 0.18.0:
```shell-session
$ boundary version
```
1. In the CLI, run the status command to confirm that the Boundary Client Agent has started:
```shell-session
$ boundary client-agent status
```
Refer to the [transparent sessions interoperability matrix](/boundary/docs/configuration/target-aliases/interoperability-matrix) for a list of the third-party products that have been tested for use with the Boundary installer and Client Agent.
## Configure targets
The following section details how to configure targets and use transparent sessions.
<Tip>
If you use a cluster that was created earlier than release 0.16.0, you must add the grant `list-resolvable-aliases` so that the client agent can populate the local alias cache.
As an example, you could add the grant:
`type=user;actions=list-resolvable-aliases;ids=*`.
For more information, refer to the [Grants](/boundary/docs/api-clients/client-agent#grants) section in the Client Agent documentation.
</Tip>
Complete the following steps to configure targets and test transparent sessions:
1. Authenticate to Boundary using the CLI or Desktop client.
1. [Create a new target with an alias](/boundary/docs/concepts/aliases#create-an-alias-during-target-creation) or [create an alias for an existing target](/boundary/docs/concepts/aliases#create-an-alias-for-an-existing-target).
Ensure that you have authorization to establish a session to the target.
1. Open the client of your choice and [connect to your target using the alias](/boundary/docs/concepts/aliases#connect-to-a-target-using-an-alias).
Boundary routes your session using the Boundary Client Agent.
You can validate that Boundary routed the session by looking at the **Sessions** page in the Desktop client, by typing `boundary sessions list -recursive` in the CLI, or by looking at sessions managed by the Client Agent using `boundary client-agent sessions`.
<Note>
The Client Agent periodically requests an updated list of aliases from the controller, so the alias may not work immediately after you create it.
The alias should be updated in the Client Agent within 2 minutes. If you still see connection issues after 2 minutes, follow the troubleshooting steps in [the Client Agent troubleshooting guide](/boundary/docs/api-clients/client-agent#troubleshooting).
</Note>
When you have validated that transparent sessions work, you can create and establish transparent sessions to other services.
To establish transparent sessions to other services:
1. Make a list of the services you use.
1. Create workers as needed for network partitions.
1. Add the services to Boundary as targets.
1. [Create aliases for the targets](/boundary/docs/configuration/target-aliases/create-target-alias).
1. Connect to the target using your client of choice.
## Connect using transparent sessions
Without transparent sessions, you must use the [Boundary connect helpers](/boundary/docs/concepts/connection-workflows) to establish a session:
```shell-session
$ boundary connect ssh -target-name sql-database -target-scope-name -staging
```
Alternatively, you can use the Boundary Desktop Client to start a session, and connect on a local port supplied by Boundary:
```shell-session
$ ssh 127.0.0.1 -p 55374
```
With transparent sessions, you use the target alias as the address to establish a session. If the [client agent is running](#install-the-boundary-clients) and you have authenticated using the CLI or Boundary Desktop Client, you can use the alias to start a session:
```shell-session
$ ssh my.alias.name
```
Boundary starts the session as usual, and brokers or injects any credentials you have configured.
website/content/docs/configuration/worker/index.mdx
-222
View File
@@ -1,222 +0,0 @@
---
layout: docs
page_title: Worker configuration overview
description: >-
Learn about worker configuration for proxies, storage, and tags. Understand how multi-hop configurations let you chain workers together in private networks.
---
# Worker stanza
The `worker` stanza configures Boundary worker-specific parameters.
All workers within Boundary use certificates and encryption keys to identify
themselves and protect data in transit. However, there are three different
ways to register them so that registration of workers can fit into any workflow: controller-led, worker-led, and via external KMS.
The sub-pages linked at the bottom of this page explain the differences in their configuration.
You must register workers using the worker-led or controller-led methods in the system with an API call. These workers require storage on disk to store the current set of credentials. Workers using an external KMS auto-register after authenticating. This makes them an easy mechanism to use for automatic scaling.
This also means they do not need to store
credentials locally; the KMS re-authenticates them each time they connect.
<Note title="Important">
Before version 0.15 of Boundary, there were two different types of workers, PKI & KMS workers.
If you are using pre-0.15 workers with pre-0.15 upstream configurations, please switch the documentation version to `0.13.x` - `0.14.x`. This will ensure you have the correct information.
</Note>
## Common worker parameters
The following fields apply to all registration mechanisms.
```hcl
worker {
public_addr = "5.1.23.198"
# Local storage path required if session recording is enabled
recording_storage_path = "tmp/boundary/"
# Minimum available disk space required in the local storage path if session recording is enabled
recording_storage_minimum_available_capacity = "500MB"
# Mutually exclusive with hcp_boundary_cluster_id
initial_upstreams = [
"10.0.0.1",
"10.0.0.2",
]
tags {
type = ["prod", "webservers"]
region = ["us-east-1"]
}
# HCP Boundary only
# hcp_boundary_cluster_id = "....."
}
```
- `public_addr` - Specifies the public host or IP address (and optionally port)
where clients can reach the worker for proxying. By default, it uses the
address of the listener marked for `proxy` purpose. This is useful for cloud
environments that do not bind a publicly accessible IP directly to a NIC on
the host, such as an Amazon EIP.
You should omit this parameter in multi-hop configurations if this self-managed worker connects to an upstream HCP-managed worker.
This value can reference any of the following:
- a direct address string
- read an address from a file on disk (file://)
- read an address from an environment variable (env://)
- `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 environment variable (`env://`) from which to read the addresses. When
using environment variable or file, their contents must formatted as a JSON array:
`["127.0.0.1", "192.168.0.1", "10.0.0.1"]`
Self-managed workers connecting to HCP Boundary require the [`hcp_boundary_cluster_id`](/boundary/docs/configuration/worker/#hcp_boundary_cluster_id) parameter instead of `initial upstreams`, unless you are configuring an HCP-managed worker as an ingress worker.
If you configure a self-managed worker with both `initial_upstreams` and `hcp_boundary_cluster_id`, the worker configuration fails.
- `hcp_boundary_cluster_id` - A string required to configure workers using worker-led or controller-led registration
to connect to your HCP Boundary cluster rather than specifying
`initial_upstreams`. This parameter is valid only for workers using the worker-led or controller-led
registration method and for workers directly connected to HCP Boundary.
- `recording_storage_path` - A path to the local storage for recorded sessions.
Boundary stores session recordings in the local storage while they are in progress.
When the session is complete, Boundary moves the local session recording to remote storage and deletes the local copy.
- `recording_storage_minimum_available_capacity` - A value measured in bytes that
defines the worker's local storage state. Boundary compares this value to the available local disk space found in the `recording_storage_path` and determines if a worker can perform session recording operations.
The supported suffixes are kb, kib, mb, mib, gb, gib, tb, tib, which are not case sensitive. Example: 2GB, 2gb, 2GiB, 2gib.
The possible storage states based on the `recording_storage_minimum_available_capacity` are:
- Available - The worker has storage above the threshold and can proxy sessions that have session recording enabled.
- Low storage - The worker has storage below the threshold. It allows existing sessions to continue without interruption but prevents proxying new sessions that have session recording enabled. The worker cannot record new sessions or play back existing recordings.
- Critically low storage - The worker falls below half the storage threshold. It forcefully closes existing sessions with session recording. The worker cannot record new sessions or play back existing recordings.
- Out of storage - The worker is out of local disk space. It cannot record new sessions or play back existing recordings. The worker enters an unrecoverable state, requiring an administrator to intervene and resolve the issue.
- Not configured - The worker lacks a configured local storage path.
- Unknown - The worker starts with this default local storage state. This state indicates that the worker's local storage state is not yet known.
- `tags` - A map of key-value pairs where values are an array of strings. Most
commonly used for [filtering](/boundary/docs/concepts/filtering) targets a
worker can proxy via [worker
tags](/boundary/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 environment variable (`env://`).
## Signals
The `SIGHUP` signal causes a worker to reload its configuration file to pick up any updates for the `initial_upstreams` and `tags` values.
Boundary ignores other updated values.
The `SIGTERM` and `SIGINT` signals initiate a graceful shutdown on a worker. The worker waits for any sessions to drain
before shutting down. Workers in a graceful shutdown state do not receive any new work, including session proxying, from the control plane.
## Multi-hop worker capabilities
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Multi-hop capabilities, including multi-hop sessions and Vault private access,
is when a session or Vault credential request goes through more than one worker.
To enable this, you must connect two or more workers to each other in some
configuration. There are no limits on the number of workers allowed in a
multi-hop session configuration.
It helps to think of “upstream” and “downstream” nodes in the context of
multi-hop. If you view controllers as the “top” node of a multi-hop chain, any
worker connected to a node is "downstream" of that node. The node that any
particular worker connects to (whether another worker or a controller) is the
"upstream" of that node. For example, in the diagram below, Worker 2’s upstream
is Worker 1, and its downstream is Worker 3.
![multi-hop workers](/img/multi-hop-workers.png)
You can deploy multi-hop workers in scenarios where inbound network traffic is
not allowed. A worker in a private network can send outbound communication to
its upstream worker, and create a reverse proxy to establish a session.
You can configure [target worker filters][] with multi-hop workers to allow for
fine-grained control on which workers handle ingress and egress for session
traffic to a [target][]. Ingress worker filters specify the workers you use to initiate a session, and egress worker filters specify the workers you use to access targets.
### Multi-hop worker requirements
When you configure multi-hop sessions, there is an "ingress" worker, an "egress"
worker, and any number of intermediary workers. Ingress, egress, and
intermediary workers have the following requirements.
#### Ingress worker requirements
To proxy target connections, ingress workers require outbound access to the
Boundary control plane and inbound access from clients.
#### Intermediary worker requirements
Intermediary workers require outbound access to an upstream worker. The upstream
worker may be an ingress worker or another intermediary worker. Intermediary
workers also require inbound access from a downstream worker. The downstream
worker may be an egress worker or another intermediary worker.
#### Egress worker requirements
To proxy target connections, egress workers require outbound access to an
upstream worker and outbound access to the destination host or service.
## Complete configuration example
```hcl
listener "tcp" {
purpose = "proxy"
tls_disable = true
address = "127.0.0.1"
}
worker {
# Path for worker storage, assuming worker-led or controller-led registration. Must be unique across workers
auth_storage_path="/boundary/demo-worker-1"
# Local storage path required if session recording is enabled
recording_storage_path = "tmp/boundary/"
# Minimum available disk space required in the local storage path if session recording is enabled
recording_storage_minimum_available_capacity = "500MB"
# 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"]
}
}
# The following KMS config is an example only
# Use a production KMS such as AWS KMS for production installs
kms "aead" {
purpose = "worker-auth-storage"
aead_type = "aes-gcm"
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
key_id = "worker-auth-storage"
}
```
## Tutorials
Refer to the [Self-Managed Worker Registration with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-workers) tutorial to learn how to register and manage Workers.
Refer to the [Manage Multi-Hop Sessions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-multi-hop) tutorial to learn how to configure a multi-hop session.
[Worker Configuration Methods]: /boundary/docs/configuration/worker/worker-configuration
[target]: /boundary/docs/concepts/domain-model/targets
[target worker filters]: /boundary/docs/concepts/filtering/worker-tags#target-worker-filtering
[session recording]: /boundary/docs/configuration/session-recording
website/content/docs/configuration/workers.mdx
+16
View File
@@ -0,0 +1,16 @@
---
layout: docs
page_title: Worker stanza
description: >-
Learn about how to configure workers for proxies, storage, and tags.
---
# worker stanza
The `worker` stanza configures Boundary worker-specific parameters.
@include '/configuration-reference/workers/common-worker-parameters.mdx'
## Complete configuration example
@include '/configuration-reference/workers/complete-configuration-example.mdx'
website/content/docs/configuration/credential-management/configure-credential-brokering.mdx → website/content/docs/credentials/configure-credential-brokering.mdx
+5 -5
View File
@@ -16,8 +16,8 @@ When you use credential brokering, Boundary returns credentials to the user when
- You must have configured either a static credential store or a Vault credential store:
- To configure a static credential store, refer to [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary).
- To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault).
- To configure a static credential store, refer to [Create static credential stores](/boundary/docs/credentials/static-cred-boundary).
- To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/credentials/static-cred-vault).
- You must have a static credential saved in your static credential store or Vault credential store. The credential must correspond to the target you want to authenticate to.
@@ -73,6 +73,6 @@ Complete the following steps to configure credential brokering for a target:
Refer to the following topics for more information:
- [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary)
- [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault)
- [Target types](/boundary/docs/concepts/domain-model/targets#target-types)
- [Create static credential stores](/boundary/docs/credentials/static-cred-boundary)
- [Create Vault credential stores](/boundary/docs/credentials/static-cred-vault)
- [Target types](/boundary/docs/domain-model/targets#target-types)
website/content/docs/configuration/credential-management/configure-credential-injection.mdx → website/content/docs/credentials/configure-credential-injection.mdx
+6 -6
View File
@@ -19,8 +19,8 @@ Credential injection provides end users with a passwordless experience when they
- You must have configured either a static credential store or a Vault credential store:
- To configure a static credential store, refer to [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary).
- To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault).
- To configure a static credential store, refer to [Create static credential stores](/boundary/docs/credentials/static-cred-boundary).
- To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/credentials/static-cred-vault).
- You must have a static credential saved in your static credential store or Vault credential store. The credential must correspond to the target to which you want to authenticate.
@@ -79,7 +79,7 @@ Complete the following steps to configure targets with credential injection:
Refer to the following topics for more information:
- [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary)
- [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault)
- [Target types](/boundary/docs/concepts/domain-model/targets#target-types)
- [Credentials](/boundary/docs/concepts/domain-model/credentials)
- [Create static credential stores](/boundary/docs/credentials/static-cred-boundary)
- [Create Vault credential stores](/boundary/docs/credentials/static-cred-vault)
- [Target types](/boundary/docs/domain-model/targets#target-types)
- [Credentials](/boundary/docs/domain-model/credentials)
website/content/docs/configuration/credential-management/index.mdx → website/content/docs/credentials/index.mdx
+7 -7
View File
@@ -5,13 +5,13 @@ description: >-
Credential stores let you store and manage credentials in Boundary. Learn about configuring user workflows with credential management or credential injection.
---
# Overview
# Credentials in Boundary
When users connect to a target machine, they typically need a set of credentials for authentication. Rather than requiring users to securely store and manage credentials for every target resource, Boundary centralizes credential management to enhance security.
## Credential stores
Boundary supports credential management using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets.
Boundary supports credential management using [credential stores](/boundary/docs/domain-model/credential-stores), which are resources that store credentials for various targets.
There are two types of credential stores:
@@ -34,13 +34,13 @@ The third workflow uses a featured called credential injection, where credential
The type of target you connect to also determines which credential workflows you can configure.
An SSH target must have at least one injected application credential to establish the SSH connection.
A TCP target cannot have any injected application credentials.
For more information, refer to the [Target types](/boundary/docs/concepts/domain-model/targets#target-types) documentation.
For more information, refer to the [Target types](/boundary/docs/domain-model/targets#target-types) documentation.
## Next steps
The following pages provide steps to configure static credentials using both a static credential store and a Vault credential store. You can also configure targets for either credential brokering or credential injection workflows.
- [Create a static credential store](/boundary/docs/configuration/credential-management/static-cred-boundary)
- [Create a Vault credential store](/boundary/docs/configuration/credential-management/static-cred-vault)
- [Configure targets with credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering)
- [Configure targets with credential injection](/boundary/docs/configuration/credential-management/configure-credential-injection)
- [Create a static credential store](/boundary/docs/credentials/static-cred-boundary)
- [Create a Vault credential store](/boundary/docs/credentials/static-cred-vault)
- [Configure targets with credential brokering](/boundary/docs/credentials/configure-credential-brokering)
- [Configure targets with credential injection](/boundary/docs/credentials/configure-credential-injection)
website/content/docs/configuration/credential-management/static-cred-boundary.mdx → website/content/docs/credentials/static-cred-boundary.mdx
+3 -3
View File
@@ -7,7 +7,7 @@ description: >-
# Create a static credential store
You can manage credentials in Boundary using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets.
You can manage credentials in Boundary using [credential stores](/boundary/docs/domain-model/credential-stores), which are resources that store credentials for various targets.
Static credential stores are built into Boundary and only store static credentials like username and password or keypairs.
## Requirements
@@ -106,5 +106,5 @@ Once you have created a credential store, you can configure targets for credenti
When you use credential brokering, Boundary centrally manages credentials and returns them to the user when they attempt to connect to a target.
Credential injection requires HCP Boundary or Boundary Enterprise, and it provides end users with a passwordless experience when they connect to targets.
- [Configure a target for credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering)
- [Configure a target for credential injection](/boundary/docs/configuration/credential-management/configure-credential-brokering)
- [Configure a target for credential brokering](/boundary/docs/credentials/configure-credential-brokering)
- [Configure a target for credential injection](/boundary/docs/credentials/configure-credential-brokering)
website/content/docs/configuration/credential-management/static-cred-vault.mdx → website/content/docs/credentials/static-cred-vault.mdx
+8 -4
View File
@@ -7,7 +7,7 @@ description: >-
# Create a Vault credential store
You can manage credentials in Boundary using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets.
You can manage credentials in Boundary using [credential stores](/boundary/docs/domain-model/credential-stores), which are resources that store credentials for various targets.
Vault credential stores point to a HashiCorp Vault instance, which provides capabilities like generating short-lived dynamic credentials.
## Requirements
@@ -32,7 +32,7 @@ Complete the following steps to create a Vault credential store:
1. Provide a name for your credential store and select type **Vault**.
1. Complete the fields related to your Vault instance:
- **Address** - The address of your Vault instance.
- **Worker Filter** (optional) - If your Vault instance does not have a publicly accessible address and instead is proxied through a Boundary worker, enter the worker filter. This should be a boolean expression. To generate a worker filter in the correct format, toggle the **Show filter generator** switch. Refer to the examples in the [Worker tags](/boundary/docs/concepts/filtering/worker-tags) documentation.
- **Worker Filter** (optional) - If your Vault instance does not have a publicly accessible address and instead is proxied through a Boundary worker, enter the worker filter. This should be a boolean expression. To generate a worker filter in the correct format, toggle the **Show filter generator** switch. Refer to the examples in the [Worker tags](/boundary/docs/workers/worker-tags) documentation.
- **Token** - Token provided by Vault that provides access to the static credentials within your Vault instance.
- **Namespace** (optional) - Vault namespace. Requires Vault Enterprise.
- **TLS Server Name** (optional) - Name to use as the SNI host if you connect to Vault via TLS.
@@ -95,11 +95,15 @@ Complete the following steps to create a Vault credential store:
</Tab>
</Tabs>
## More information
Refer to [Filtering and listing resources](/boundary/docs/filtering) for more information about Boundary's filter syntax and best practices.
## Next steps
Once you have created a credential store, you can configure targets for credential brokering or credential injection.
When you use credential brokering, Boundary centrally manages credentials and returns them to the user when they attempt to connect to a target.
Credential injection requires HCP Boundary or Boundary Enterprise, and it provides end users with a passwordless experience when they connect to targets.
- [Configure a target for credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering)
- [Configure a target for credential injection](/boundary/docs/configuration/credential-management/configure-credential-brokering)
- [Configure a target for credential brokering](/boundary/docs/credentials/configure-credential-brokering)
- [Configure a target for credential injection](/boundary/docs/credentials/configure-credential-brokering)
website/content/docs/install-boundary/configure-controllers.mdx → website/content/docs/deploy/self-managed/configure-controllers.mdx
+11 -9
View File
@@ -50,7 +50,7 @@ If you do not add a BSR key to your controller configuration, you receive an err
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.
Refer to [Data security in Boundary](/boundary/docs/concepts/security/data-encryption) for more information.
Refer to [Data encryption in Boundary](/boundary/docs/secure/encryption/data-encryption) for more information.
<Note>
There are two types of Boundary workers, distinguished by the method by which they authenticate with the Boundary controllers.
@@ -68,7 +68,7 @@ After you create the keys in Vault or the key management system of your choice,
Boundary manages its state and configuration in a Relational Database Management System (RDBMS), PostgreSQL.
You should create, set up, and make the PostgreSQL database accessible to the Boundary controller nodes before you configure the nodes.
Refer to the [Database recommendations](/boundary/docs/install-boundary/system-requirements#database-recommendations) documentation for examples of cloud managed PostgreSQL databases.
Refer to the [Database recommendations](/boundary/docs/architecture/system-requirements#database-recommendations) documentation for examples of cloud managed PostgreSQL databases.
## Create the controller configuration
@@ -285,7 +285,7 @@ If present, `boundary server` starts a controller subprocess.
The example events configuration above is exhaustive and writes all events to both `stderr` and a file.
This configuration may or may not work for your organization's logging solution.
- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/concepts/security/data-encryption).
- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/secure/encryption/data-encryption).
Refer to the links below for configuration information for the different cloud KMS blocks:
@@ -338,11 +338,13 @@ Run the following commands to start the service:
Upon logging in to Boundary for the first time, HashiCorp recommends creating an admin user for the global and project level scopes to manage Boundary.
Creating an admin user allows you to configure targets within those scopes and manage them.
HashiCorp recommends that you use the [KMS recovery workflow](/boundary/docs/install-boundary/initialize#log-in-with-recovery-kms) to log in to Boundary for the first time.
Refer to [Creating your first login account](/boundary/docs/install-boundary/initialize#create-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the recovery KMS workflow.
HashiCorp recommends that you use the [KMS recovery workflow](/boundary/docs/deploy/self-managed/initialize#log-in-with-recovery-kms) to log in to Boundary for the first time.
Refer to [Creating your first login account](/boundary/docs/deploy/self-managed/initialize#create-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the recovery KMS workflow.
After configuring the controller, you should:
## Next steps
- [Configure Boundary workers](/boundary/docs/install-boundary/configure-workers)
- [Initialize Boundary](/boundary/docs/install-boundary/initialize)
- [Install the Boundary Clients](/boundary/docs/install-boundary/install-clients)
After you configure the controller, you should:
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
website/content/docs/deploy/self-managed/deploy-workers.mdx
+278
View File
@@ -0,0 +1,278 @@
---
layout: docs
page_title: Deploy workers
description: >-
Configure Boundary workers for a self-managed deployment, including environment files and KMS keys. Set up ingress, intermediary, and egress roles for multi-hop.
---
# Deploy workers
Before you deploy workers, you should have completed the following steps:
- Installed Boundary on at least three [controller nodes](/boundary/docs/deploy/self-managed/configure-controllers).
- Prepared or have three existing network boundaries:
- Public/DMZ network
- Intermediary network
- Private network
- Prepared three virtual machines for Boundary workers, one in each network boundary with the Boundary binary installed on it.
In the following configuration files, there are common configuration components as well as some unique components depending on the role the Boundary worker performs.
There are three files, one for each worker in a unique network boundary.
Additionally, Boundary Enterprise supports a [multi-hop configuration](/boundary/docs/workers/multi-hop) in which the Boundary workers can serve one of three purposes: an ingress worker, an ingress/egress worker, or an egress worker.
## Prepare the environment files
HashiCorp recommends using either the `env://` or `file://` notation within the configuration files, to securely provide secret configuration components to the Boundary worker binaries.
The following configuration example uses `env://` to secure AWS KMS configuration items.
When you install the Boundary binary using a package manager, it includes a unit file which configures an environment file at `/etc/boundar.d/boundary.env`.
You can use this file to set the sensitive values that are used to configure the Boundary workers.
The following file is an example of how this environment file could be configured:
<CodeBlockConfig lineNumbers filename="/etc/boundary.d/boundary.env">
```shell-session
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
</CodeBlockConfig>
In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys.
## Prepare the worker KMS keys
The worker-auth storage KMS key is used by a Worker for the encrypted storage of authentication keys.
This is recommended Workers using controller-led or worker-led methods. If it is not specified, the authentication keys are not encrypted on disk.
Optionally, if you deploy KMS authentication-driven Boundary workers, an additional KMS key must be generated to authenticate the Boundary worker with the controller.
HashiCorp strongly recommends using the Key Management System (KMS) of the cloud provider where you deploy your Boundary workers.
Keep in mind that Boundary workers must have the correct level of permissions for interacting with the cloud provider's KMS.
Refer to your cloud provider's documentation, for more information.
## Create the worker configurations
After you create the requisite key or keys in the cloud provider of your choice, you can begin configuring the workers.
The following configuration examples all employ the worker-led authorization flow.
For more information on configuring KMS authentication for Boundary workers, refer to the [KMS authentication configuration documenation](/boundary/docs/workers/registration#kms-configuration).
If you use Boundary Enterprise, you can configure multiple workers to act in three different roles: ingress, intermediary, and egress.
For Community Edition, workers only serve one role, acting as both the point of ingress and egress.
Select your Boundary edition, and complete the following steps to configure workers.
<Tabs>
<Tab heading="Enterprise">
For Boundary Enterprise, you can configure ingress, intermediary, and egress workers to take advantage of [multi-hop worker capabilities](/boundary/docs/workers#multi-hop-sessions).
Note that "ingress," "intermediary," and "egress" are general ways to describe how the respective worker interacts with resources.
A worker can serve more than one of those roles at a time.
Refer to [Multi-hop sessions](/boundary/docs/workers/multi-hop) for more information.
Complete the steps below to configure workers for Boundary Enterprise.
### Ingress worker configuration
@include '/workers/ingress-worker-config.mdx'
### Intermediate worker configuration
@include '/workers/intermediate-worker-config.mdx'
### Egress worker configuration
@include '/workers/egress-worker-config.mdx'
</Tab>
<Tab heading="Community Edition">
For the Community Edition of Boundary, you must configure a worker server that communicates with the controller and is responsible for storage-related tasks.
Boundary Community Edition only supports egress workers. To configure workers for multi-hop sessions, check the Boundary Enterprise configuration.
Complete the following steps to configure the worker.
### Worker configuration
@include '/workers/single-worker-config.mdx'
</Tab>
</Tabs>
## Start the Boundary service
When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary worker nodes using `systemd`.
Run the following commands to start the service:
1. `sudo systemctl enable boundary`
1. `sudo systemctl start boundary`
## Adopt the workers (optional)
If you use the workers as outlined above, you must adopt the Boundary workers.
Complete the following steps to adopt the workers:
<Tabs>
<Tab heading="Admin UI">
Complete the following steps to adopt the worker using the UI:
1. Log in to Boundary as the admin user.
1. Select **Workers** in the navigation pane.
1. Click **New**.
1. (Optional) You can use the workers page to construct the contents of the `worker.hcl` file, if you did not [create the configuration file](/boundary/docs/deploy/self-managed/deploy-workers#create-the-worker-configurations) as part of the installation process above.
Provide the following details, and Boundary constructs the worker configuration file for you:
- Boundary Cluster ID
- Worker Public Address
- Config file path
- Worker Tags
1. Scroll to the bottom of the **New Worker** page, and paste the **Worker Auth Registration Request** key.
Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker.
You can also locate this value in the `auth_request_token` file.
1. Click **Register Worker**.
1. Click **Done**.
The new worker appears on the **Workers** page.
1. Repeat the registration process for any other workers, such as the intermediate and egress workers.
</Tab>
<Tab heading="CLI">
Complete the following steps to adopt the worker using the CLI:
1. Use the following command to ensure that the `BOUNDARY_ADDR` is set as an environment variable:
```hcl
$ export BOUNDARY_ADDR="https://c3a7a20a-f663-40f3-a8e3-1b2f69b3625.boundary.hashicorp.cloud"
```
1. Log into the CLI as the admin user, providing the Auth Method ID, admin login name, and admin password when prompted.
```hcl
$ boundary authenticate password \
-auth-method-id=ampw_KfLAjMS2CG \
-login-name=admin
```
Example:
<CodeBlockConfig hideClipboard>
```hcl
$ boundary authenticate password \
-auth-method-id=ampw_KfLAjMS2CG \
-login-name=admin
Please enter the password (it will be hidden):
Authentication information:
Account ID: acctpw_r6crEm0FgM
Auth Method ID: ampw_KfLAjMS2CG
Expiration Time: Mon, 27 Jun 2022 22:03:28 MDT
User ID: u_ysJd0LXX9T
The token was successfully stored in the chosen keyring and is not displayed here.
```
</CodeBlockConfig>
1. Next, use the following command to export the **Worker Auth Request Token** value as an environment variable:
```shell-session
$ export WORKER_TOKEN=<Worker Auth Registration Request Value>
```
Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker.
You can also locate this value in the `auth_request_token` file.
The token is used to issue a create worker request that authorizes the worker to Boundary and makes it available.
Currently worker creation is only supported for workers with an authorization token (worker-led and controller-led).
1. Create a new worker using the worker-led registration method with the following command:
```shell-session
$ boundary workers create worker-led -worker-generated-auth-token=$WORKER_TOKEN
Worker information:
Active Connection Count: 0
Created Time: Fri, 03 Jan 2025 13:52:04 MST
ID: w_zLGjAbYx1h
Local Storage State: unknown
Type: pki
Updated Time: Fri, 03 Jan 2025 13:52:04 MST
Version: 1
Scope:
ID: global
Name: global
Type: global
Authorized Actions:
no-op
read
update
delete
add-worker-tags
set-worker-tags
remove-worker-tags
```
Confirm the worker registration and view its details by executing the following command and supplying the new worker's id:
```shell-session
$ boundary workers read -id w_zLGjAbYx1h
Worker information:
Active Connection Count: 0
Address: 127.0.0.1:9202
Created Time: Fri, 03 Jan 2025 13:52:04 MST
ID: w_zLGjAbYx1h
Last Status Time: 2025-01-03 20:58:41.346537 +0000 UTC
Local Storage State: not configured
Release Version: Boundary v0.18.1+ent
Type: pki
Updated Time: Fri, 03 Jan 2025 13:58:41 MST
Version: 1
Scope:
ID: global
Name: global
Type: global
Tags:
Configuration:
type: ["worker1" "upstream"]
Canonical:
type: ["upstream" "worker1"]
Authorized Actions:
add-worker-tags
set-worker-tags
remove-worker-tags
no-op
read
update
delete
```
1. Repeat the registration process for any other workers, such as the intermediate and egress workers.
</Tab>
</Tabs>
## Next steps
After you configure workers, you should:
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
website/content/docs/deploy/self-managed/index.mdx
+51
View File
@@ -0,0 +1,51 @@
---
layout: docs
page_title: Deploy Boundary in a self-managed environment
description: >-
Discover resources for deploying a self-managed version of Boundary Enterprise or Boundary Community Edition.
---
# Deploy Boundary in a self-managed environment
To deploy a self-managed Boundary environment you should:
1. Install the Boundary binary
1. Deploy and configure Boundary controllers and workers
1. Install end-user clients
This guide outlines the required steps to manually install and configure a
single self-managed HashiCorp Boundary cluster as defined in the Recommended
architecture topic.
It assumes you install Boundary on virtual machines (VMs) or bare-metal servers
running a Debian or Red Hat-based Linux distribution.
To deploy HCP Boundary instead, refer to the [Deploy and log in](/boundary/docs/hcp/get-started/deploy-and-login) in the HCP Boundary Get started documentation.
This document includes general guidance as well as specific recommendations for
popular cloud infrastructure platforms. These recommendations have also been
encoded into official Terraform reference architectures for
[AWS](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/aws),
[Azure](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/azure),
and
[GCP](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/gcp).
## More information
Before you begin, you may want to review the following information about Boundary's architecture and system requirements:
- [System requirements](/boundary/docs/architecture/system-requirements)
- [Recommended architecture](/boundary/docs/architecture/recommended-architecture)
- [Fault tolerance](/boundary/docs/architecture/fault-tolerance)
- [High availability](/boundary/docs/architecture/high-availability)
## Next steps
Refer to the following topics to deploy your self-managed environment:
1. [Install Boundary](/boundary/docs/deploy/self-managed/install)
1. [Configure controllers](/boundary/docs/deploy/self-managed/configure-controllers)
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
1. [Install Boundary clients](/boundary/docs/deploy/self-managed/install-clients)
To configure Boundary resources using Terraform, refer to [Terraform patterns](/boundary/docs/deploy/terraform-patterns).
website/content/docs/install-boundary/initialize.mdx → website/content/docs/deploy/self-managed/initialize.mdx
+4 -6
View File
@@ -10,11 +10,11 @@ description: >-
This document describes how to access Boundary for the first time and create the necessary resources to log in as a
user.
You can also initialize and manage Boundary using Terraform. Refer to the [Terraform patterns](/boundary/docs/install-boundary/terraform-patterns) page to learn more.
You can also initialize and manage Boundary using Terraform. Refer to the [Terraform patterns](/boundary/docs/deploy/terraform-patterns) page to learn more.
## Requirements
Before you initialize Boundary, you should have [initialized a database](/boundary/docs/install-boundary/configure-controllers#initialize-the-database).
Before you initialize Boundary, you should have [initialized a database](/boundary/docs/deploy/self-managed/configure-controllers#initialize-the-database).
## Log in with recovery KMS
@@ -463,8 +463,6 @@ boundary authenticate password \
-auth-method-id <auth_method_id>
```
After initializing Boundary, you should:
## Next steps
Next, you should:
- [Install the Boundary Clients](/boundary/docs/install-boundary/install-clients)
After you initialize Boundary, you should [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients).
website/content/docs/install-boundary/install-clients.mdx → website/content/docs/deploy/self-managed/install-clients.mdx
+4 -4
View File
@@ -11,7 +11,7 @@ Boundary end users access infrastructure targets using the Boundary Desktop Clie
This guide outlines the required steps to manually install and configure a Boundary client depending on which distribution of Boundary end users access.
To learn about installing the Boundary binary when you deploy Boundary controllers or workers, refer to the [Deploy Boundary](/boundary/docs/install-boundary/deploy) page.
To learn about installing the Boundary binary when you deploy Boundary controllers or workers, refer to the [Install Boundary](/boundary/docs/deploy/self-managed/install) page.
Select your Boundary distribution, and complete the steps to install the
correct clients:
@@ -27,7 +27,7 @@ The Boundary installer bundles together the following components:
- Boundary Desktop Client app
- Boundary Client Agent <sup>HCP/ENT</sup>
Download the appropriate Boundary installer for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install#installer) page or the [releases](https://releases.hashicorp.com/boundary-installer) page. You can also download the components individually, but compatibility is not guaranteed. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
Download the appropriate Boundary installer for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install#installer) downloads page or the [releases](https://releases.hashicorp.com/boundary-installer) page. You can also download the components individually, but compatibility is not guaranteed. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
<Warning>
@@ -45,11 +45,11 @@ We recommend the following components for end users:
- Boundary binary (CLI)
- Boundary Desktop Client app
Download these components for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install) page or the [HashiCorp releases](https://releases.hashicorp.com/) page.
Download these components for your Windows, MacOS, or Linux environment from the [Install Boundary](/boundary/install) downloads page or the [HashiCorp releases](https://releases.hashicorp.com/) page.
<Warning>
Client compatibility is not guaranteed. You should always ensure that your client is compatible with the version of the Boundary control plane you are connecting to. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
Client compatibility is not guaranteed. You should always ensure that your client is compatible with the version of the Boundary control plane you connect to. Refer to the [Supported versions policy](/boundary/docs/enterprise/supported-versions#control-plane-and-client-cli-compatibility) to learn more.
</Warning>
website/content/docs/install-boundary/deploy.mdx → website/content/docs/deploy/self-managed/install.mdx
+10 -29
View File
@@ -1,32 +1,11 @@
---
layout: docs
page_title: Deploy Boundary
page_title: Install Boundary
description: >-
Deploy a self-managed version of Boundary Enterprise or Community Edition on Ubuntu/Debian, CentOS/RHEL, or Amazon Linux by installing the binary file.
---
# Deploy Boundary
To deploy a self-managed Boundary environment you should:
1. Deploy and configure Boundary controllers and workers
2. Install end-user clients
This guide outlines the required steps to manually install and configure a
single HashiCorp Boundary cluster as defined in the [Recommended
architecture](/boundary/docs/install-boundary/recommended-architecture) topic.
It assumes you install Boundary on virtual machines (VMs) or bare-metal servers
running a Debian or Red Hat-based Linux distribution.
To learn about installing end-user clients, refer to the [Install Boundary clients](/boundary/docs/install-boundary/install-clients) page.
This document includes general guidance as well as specific recommendations for
popular cloud infrastructure platforms. These recommendations have also been
encoded into official Terraform reference architectures for
[AWS](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/aws),
[Azure](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/azure),
and
[GCP](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/gcp).
# Install Boundary
Pre-built Boundary packages are available from the [HashiCorp Linux
Repository](https://www.hashicorp.com/blog/announcing-the-hashicorp-linux-repository).
@@ -203,11 +182,13 @@ binary:
</Tab>
</Tabs>
You should install the binary on the controller and worker instances you configure to run in your Boundary environments.
You should install the binary on the controller and worker instances you configure to run in your Boundary environments.
Next, you should:
## Next steps
- [Configure Boundary controllers](/boundary/docs/install-boundary/configure-controllers)
- [Configure Boundary workers](/boundary/docs/install-boundary/configure-workers)
- [Initialize Boundary](/boundary/docs/install-boundary/initialize)
- [Install the Boundary Clients](/boundary/docs/install-boundary/install-clients)
After you install the binary, you should:
1. [Configure controllers](/boundary/docs/deploy/self-managed/configure-controllers)
1. [Deploy workers](/boundary/docs/deploy/self-managed/deploy-workers)
1. [Initialize Boundary](/boundary/docs/deploy/self-managed/initialize)
1. [Install the Boundary Clients](/boundary/docs/deploy/self-managed/install-clients)
website/content/docs/install-boundary/systemd.mdx → website/content/docs/deploy/self-managed/systemd.mdx
+1 -1
View File
@@ -13,7 +13,7 @@ This section covers how to install Boundary under the [systemd](https://systemd.
`TYPE` below can be either `worker` or `controller` if you want to run them independently, e.g. for high availability. If you want to run combined nodes, modify as desired.
1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service.
1. `/etc/boundary.d/boundary-${TYPE}.hcl`: Configuration file for the boundary service.
2. `/usr/local/bin/boundary`: The Boundary binary, which can be built from the [source](https://github.com/hashicorp/boundary) or downloaded from our [release page](/boundary/downloads).
website/content/docs/install-boundary/terraform-patterns/index.mdx → website/content/docs/deploy/terraform-patterns/index.mdx
+9 -9
View File
@@ -15,8 +15,8 @@ This following topics outline MVP (Minimum Viable Product) patterns to deploy an
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
## Terraform provider configuration
@@ -55,10 +55,10 @@ The following pages provide examples and patterns for configuring Boundary resou
If you are configuring Boundary resources for the first time, you may want to start by creating a scope.
You create scopes to partition resources and then assign ownership of those resources to users and groups.
- [Scopes](/boundary/docs/install-boundary/terraform-patterns/terraform-scopes)
- [Users and auth methods](/boundary/docs/install-boundary/terraform-patterns/terraform-users-and-auth-methods)
- [Groups and role-based-access-control (RBAC)](/boundary/docs/install-boundary/terraform-patterns/terraform-groups-and-rbac)
- [Hosts and host management](/boundary/docs/install-boundary/terraform-patterns/terraform-hosts-and-host-management)
- [Credentials and credential stores](/boundary/docs/install-boundary/terraform-patterns/terraform-credentials-and-credential-stores)
- [Session recording](/boundary/docs/install-boundary/terraform-patterns/terraform-session-recording)
- [Targets](/boundary/docs/install-boundary/terraform-patterns/terraform-targets)
- [Scopes](/boundary/docs/deploy/terraform-patterns/terraform-scopes)
- [Users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods)
- [Groups and role-based-access-control (RBAC)](/boundary/docs/deploy/terraform-patterns/terraform-groups-and-rbac)
- [Hosts and host management](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management)
- [Credentials and credential stores](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores)
- [Session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording)
- [Targets](/boundary/docs/deploy/terraform-patterns/terraform-targets)
website/content/docs/install-boundary/terraform-patterns/terraform-credentials-and-credential-stores.mdx → website/content/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores.mdx
+10 -10
View File
@@ -1,11 +1,11 @@
---
layout: docs
page_title: Terraform patterns for Boundary credentials and credential stores
page_title: Terraform patterns for credentials and credential stores
description: >-
Use Terraform patterns to create and manage Boundary credentials and credential stores. Learn how to create static or Vault credential stores, add credentials.
---
# Terraform patterns for Boundary credentials and credential stores
# Terraform patterns for credentials and credential stores
Boundary supports multiple types of static credentials and Vault dynamic credentials. A credential store stores credentials for hosts. Static credential stores can hold username/passwords, JSON tokens, SSH key pairs, and SSH certificates.
@@ -13,10 +13,10 @@ Boundary supports multiple types of static credentials and Vault dynamic credent
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- Configured [hosts](/boundary/docs/install-boundary/terraform-patterns/terraform-hosts-and-host-management) for any credential store you plan to create.
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
- Configured [hosts](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management) for any credential store you plan to create.
## Static credential store configuration
@@ -177,9 +177,9 @@ resource "boundary_credential_library_vault_ssh_certificate" "example" {
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Credential stores](/boundary/docs/concepts/domain-model/credential-stores)
- [Credentials](/boundary/docs/concepts/domain-model/credentials)
- [Credential libraries](/boundary/docs/concepts/domain-model/credential-libraries)
- [Credential stores](/boundary/docs/domain-model/credential-stores)
- [Credentials](/boundary/docs/domain-model/credentials)
- [Credential libraries](/boundary/docs/domain-model/credential-libraries)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
@@ -196,4 +196,4 @@ For more information about managing the following resources using Terraform, ref
## Next steps
Once you have configured credentials and credential stores, you may want to enable [session recording](/boundary/docs/install-boundary/terraform-patterns/terraform-session-recording) for auditing purposes or configure [targets](/boundary/docs/install-boundary/terraform-patterns/terraform-targets) for your users to connect to.
Once you have configured credentials and credential stores, you may want to enable [session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording) for auditing purposes or configure [targets](/boundary/docs/deploy/terraform-patterns/terraform-targets) for your users to connect to.
website/content/docs/install-boundary/terraform-patterns/terraform-groups-and-rbac.mdx → website/content/docs/deploy/terraform-patterns/terraform-groups-and-rbac.mdx
+11 -11
View File
@@ -1,11 +1,11 @@
---
layout: docs
page_title: Terraform patterns for Boundary groups and RBAC
page_title: Terraform patterns for groups and RBAC
description: >-
Use Terraform patterns to create and manage Boundary groups and role-based access control (RBAC). Learn how to add users to managed groups and assign roles.
---
# Terraform patterns for Boundary groups and RBAC
# Terraform patterns for groups and RBAC
The following pattern demonstrates how to aggregate users into groups.
@@ -17,10 +17,10 @@ In Boundary, you can assign users directly to a role, but a better pattern is to
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- Created Boundary [users and auth methods](/boundary/docs/install-boundary/terraform-patterns/terraform-users-and-auth-methods) to assign to the group you plan to create.
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
- Created Boundary [users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods) to assign to the group you plan to create.
## Group configuration
@@ -78,10 +78,10 @@ resource "boundary_role" "readonly" {
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Roles](/boundary/docs/concepts/domain-model/roles)
- [Groups](/boundary/docs/concepts/domain-model/groups)
- [Managed groups](/boundary/docs/concepts/domain-model/managed-groups)
- [Grants](/boundary/docs/concepts/security/permissions#grant-strings)
- [Roles](/boundary/docs/domain-model/roles)
- [Groups](/boundary/docs/domain-model/groups)
- [Managed groups](/boundary/docs/domain-model/managed-groups)
- [Grants](/boundary/docs/rbac#grant-strings)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
@@ -96,5 +96,5 @@ For more information about managing the following resources using Terraform, ref
## Next steps
You may want to create [hosts and host sets](/boundary/docs/install-boundary/terraform-patterns/terraform-hosts-and-host-management) so that you can configure targets for your users to connect to.
You may want to create [hosts and host sets](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management) so that you can configure targets for your users to connect to.
Targets require an address or host, and credentials to connect to that host.
website/content/docs/install-boundary/terraform-patterns/terraform-hosts-and-host-management.mdx → website/content/docs/deploy/terraform-patterns/terraform-hosts-and-host-management.mdx
+12 -10
View File
@@ -1,11 +1,11 @@
---
layout: docs
page_title: Terraform patterns for Boundary hosts and host management
page_title: Terraform patterns for hosts and host management
description: >-
Use Terraform patterns to create and manage Boundary hosts and host catalogs. Learn how to add static or plugin-based hosts to static or dynamic host catalogs.
---
# Terraform patterns for Boundary hosts and host management
# Terraform patterns for hosts and host management
Before you can access a system, you must create a target. Targets require an address or host, and credentials to connect to that host.
@@ -16,9 +16,9 @@ Instead, HashiCorp recommends adding hosts to a host set, and then attaching the
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
## Static host catalog configuration
@@ -134,10 +134,10 @@ resource "boundary_host_set_plugin" "web" {
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Targets](/boundary/docs/concepts/domain-model/targets)
- [Hosts](/boundary/docs/concepts/domain-model/hosts)
- [Host sets](/boundary/docs/concepts/domain-model/host-sets)
- [Host catalogs](/boundary/docs/concepts/domain-model/host-catalogs)
- [Targets](/boundary/docs/domain-model/targets)
- [Hosts](/boundary/docs/domain-model/hosts)
- [Host sets](/boundary/docs/domain-model/host-sets)
- [Host catalogs](/boundary/docs/domain-model/host-catalogs)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
@@ -147,6 +147,8 @@ For more information about managing the following resources using Terraform, ref
- [Plugin-based host catalogs](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_catalog_plugin/)
- [Plugin-based host sets](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/host_set_plugin/)
Refer to [Filtering and listing resources](/boundary/docs/filtering) for more information about Boundary's filter syntax and best practices.
## Next steps
Once you have configured hosts, you may want to configure [credentials and credential stores](/boundary/docs/install-boundary/terraform-patterns/terraform-credentials-and-credential-stores) for your hosts and users.
Once you have configured hosts, you may want to configure [credentials and credential stores](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores) for your hosts and users.
website/content/docs/install-boundary/terraform-patterns/terraform-scopes.mdx → website/content/docs/deploy/terraform-patterns/terraform-scopes.mdx
+9 -9
View File
@@ -1,11 +1,11 @@
---
layout: docs
page_title: Terraform patterns for Boundary scopes
page_title: Terraform patterns for scopes
description: >-
Use Terraform patterns to create and manage Boundary scopes. Learn how to configure global, org-level, and project-level scopes using the Boundary provider.
---
# Terraform patterns for Boundary scopes
# Terraform patterns for scopes
You can use the following patterns to create org-level and project-level scopes.
@@ -13,9 +13,9 @@ You can use the following patterns to create org-level and project-level scopes.
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
## Scopes configuration
@@ -45,9 +45,9 @@ resource "boundary_scope" "project" {
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Scopes](/boundary/docs/concepts/domain-model/scopes)
- [Org-level scopes](/boundary/docs/concepts/domain-model/scopes#organizations)
- [Project-level scopes](/boundary/docs/concepts/domain-model/scopes#projects)
- [Scopes](/boundary/docs/domain-model/scopes)
- [Org-level scopes](/boundary/docs/domain-model/scopes#organizations)
- [Project-level scopes](/boundary/docs/domain-model/scopes#projects)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
@@ -56,4 +56,4 @@ For more information about managing the following resources using Terraform, ref
## Next steps
You use scopes to partition resources and assign them to users.
Once you have created scopes, you may want to create [users and auth methods](/boundary/docs/install-boundary/terraform-patterns/terraform-users-and-auth-methods).
Once you have created scopes, you may want to create [users and auth methods](/boundary/docs/deploy/terraform-patterns/terraform-users-and-auth-methods).
website/content/docs/install-boundary/terraform-patterns/terraform-session-recording.mdx → website/content/docs/deploy/terraform-patterns/terraform-session-recording.mdx
+10 -10
View File
@@ -1,24 +1,24 @@
---
layout: docs
page_title: Terraform patterns for Boundary session recording
page_title: Terraform patterns for session recording
description: >-
Use Terraform patterns to enable session recording for auditing user sessions in Boundary. Learn how to configure storage policies and storage buckets.
---
# Terraform patterns for Boundary session recording
# Terraform patterns for session recording
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Session recording requires that you create a storage policy for your current scope and then allocate an AWS S3 bucket to store the recordings. This example does not demonstrate creating the S3 bucket or the associated IAM policies. Refer to the [create storage buckets](/boundary/docs/configuration/session-recording/create-storage-bucket) documentation to learn how to configure AWS.
Session recording requires that you create a storage policy for your current scope and then allocate an AWS S3 bucket to store the recordings. This example does not demonstrate creating the S3 bucket or the associated IAM policies. Refer to the [create storage buckets](/boundary/docs/session-recording/configuration/create-storage-bucket) documentation to learn how to configure AWS.
## Requirements
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- Created a [scope](/boundary/docs/install-boundary/terraform-patterns/terraform-scopes) for any storage policy you plan to create.
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
- Created a [scope](/boundary/docs/deploy/terraform-patterns/terraform-scopes) for any storage policy you plan to create.
- A licensed version of HCP Boundary or Boundary Enterprise.
## Storage policy configuration
@@ -75,8 +75,8 @@ You have configured the prerequisites for session recording. The last task is to
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Session recordings](/boundary/docs/concepts/domain-model/session-recordings)
- [Storage buckets](/boundary/docs/concepts/domain-model/storage-buckets)
- [Session recordings](/boundary/docs/domain-model/session-recordings)
- [Storage buckets](/boundary/docs/domain-model/storage-buckets)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
@@ -85,4 +85,4 @@ For more information about managing the following resources using Terraform, ref
## Next steps
Once you have configured the prerequisites for session recording, you can enable recording on a Boundary [target](/boundary/docs/install-boundary/terraform-patterns/terraform-targets).
Once you have configured the prerequisites for session recording, you can enable recording on a Boundary [target](/boundary/docs/deploy/terraform-patterns/terraform-targets).
website/content/docs/install-boundary/terraform-patterns/terraform-targets.mdx → website/content/docs/deploy/terraform-patterns/terraform-targets.mdx
+9 -9
View File
@@ -1,24 +1,24 @@
---
layout: docs
page_title: Terraform patterns for Boundary targets
page_title: Terraform patterns for targets
description: >-
Use Terraform patterns to create and manage Boundary targets. Learn how to configure SSH and TCP targets, inject passwords, and enable session recording.
---
# Terraform patterns for Boundary targets
# Terraform patterns for targets
Once you have defined a host, a host catalog, and a credential store, you
can create [targets](/boundary/docs/concepts/domain-model/targets).
can create [targets](/boundary/docs/domain-model/targets).
## Requirements
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- Defined a host, [host catalog](/boundary/docs/install-boundary/terraform-patterns/terraform-hosts-and-host-management), and [credential store](/boundary/docs/install-boundary/terraform-patterns/terraform-credentials-and-credential-stores).
- (Optional) Configured a storage policy and storage bucket for any targets you want to enable for [session recording](/boundary/docs/install-boundary/terraform-patterns/terraform-session-recording).
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
- Defined a host, [host catalog](/boundary/docs/deploy/terraform-patterns/terraform-hosts-and-host-management), and [credential store](/boundary/docs/deploy/terraform-patterns/terraform-credentials-and-credential-stores).
- (Optional) Configured a storage policy and storage bucket for any targets you want to enable for [session recording](/boundary/docs/deploy/terraform-patterns/terraform-session-recording).
## Target configuration
@@ -118,7 +118,7 @@ resource "boundary_target" "rdp_foo" {
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Targets](/boundary/docs/concepts/domain-model/targets)
- [Targets](/boundary/docs/domain-model/targets)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
website/content/docs/install-boundary/terraform-patterns/terraform-users-and-auth-methods.mdx → website/content/docs/deploy/terraform-patterns/terraform-users-and-auth-methods.mdx
+10 -10
View File
@@ -1,11 +1,11 @@
---
layout: docs
page_title: Terraform patterns for Boundary users and auth methods
page_title: Terraform patterns for users and auth methods
description: >-
Use Terraform patterns to create and manage Boundary users and auth methods. Learn how to configure password and LDAP auth methods, add accounts, create users.
---
# Terraform patterns for Boundary users and auth methods
# Terraform patterns for users and auth methods
Boundary supports password, OIDC, and LDAP auth methods.
@@ -13,10 +13,10 @@ Boundary supports password, OIDC, and LDAP auth methods.
This document assumes the reader has:
- An understanding of [Terraform](/terraform/docs) fundamentals
- An existing Boundary installation. Refer to [Initialize Boundary](/boundary/docs/install-boundary/initialize) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/install-boundary/terraform-patterns/#terraform-provider-configuration).
- Created a [scope](/boundary/docs/install-boundary/terraform-patterns/terraform-scopes) to add the users and auth methods to.
- An understanding of [Terraform](/terraform/docs) fundamentals.
- An existing Boundary installation. Refer to [Deploy Boundary in a self-managed environment](/boundary/docs/deploy/self-managed) to learn about deploying Boundary.
- Configured the [Terraform Boundary provider](/boundary/docs/deploy/terraform-patterns/#terraform-provider-configuration).
- Created a [scope](/boundary/docs/deploy/terraform-patterns/terraform-scopes) to add the users and auth methods to.
## Auth method configuration
@@ -92,9 +92,9 @@ resource "boundary_user" "susmitha" {
## More information
For more information about the Boundary resources mentioned in this topic, refer to the domain model documentation:
- [Auth methods](/boundary/docs/concepts/domain-model/auth-methods)
- [Users](/boundary/docs/concepts/domain-model/users)
- [Accounts](/boundary/docs/concepts/domain-model/accounts)
- [Auth methods](/boundary/docs/domain-model/auth-methods)
- [Users](/boundary/docs/domain-model/users)
- [Accounts](/boundary/docs/domain-model/accounts)
For more information about managing the following resources using Terraform, refer to the Boundary provider documentation:
- [LDAP accounts](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs/resources/account_ldap/)
@@ -103,4 +103,4 @@ For more information about managing the following resources using Terraform, ref
## Next steps
Once you have created users and auth methods, you may want to create [groups for your users or configure RBAC](/boundary/docs/install-boundary/terraform-patterns/terraform-groups-and-rbac) to define the actions a user is allowed to take.
Once you have created users and auth methods, you may want to create [groups for your users or configure RBAC](/boundary/docs/deploy/terraform-patterns/terraform-groups-and-rbac) to define the actions a user is allowed to take.
Loaded 100 of 253 files, more files were not shown because too many files have changed in this diff. Show more