docs: IA reorganization (#5838)
* 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:
1 parent
21fce7c5eb
commit
5ce6515156
253 files changed
+7897
-5673
No files matched your search
@@ -1,106 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: API overview
|
||||
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'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.
|
||||
|
||||
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).
|
||||
|
||||
-> **NOTE:** A rendered version of this generated API definition can be found on the [API page](/boundary/api-docs).
|
||||
|
||||
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.)
|
||||
- `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.
|
||||
- `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable as it allows for far simpler and more robust client implementation.
|
||||
- `405`: Boundary returns a `405` to indicate that the method (HTTP verb or custom action) is not implemented for the given resource.
|
||||
- `429`: Boundary returns a `429` if any of the API rate limit quotas have been exhausted for the resource and action. It includes the `Retry-After` header so that the client knows how long to wait before making a new request.
|
||||
- `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client.
|
||||
- `503`: Boundary returns a `503` if it is unable to store a quota due to the API rate limit being exceeded. It includes the `Retry-After` header so that the client knows how long to wait before making a new request.
|
||||
|
||||
## Path layout
|
||||
|
||||
Boundary follows a predictable path layout. There are two fundamental types of URL paths, each supporting a different set of operations.
|
||||
|
||||
### Collections
|
||||
|
||||
Collections of resources are top level paths with plural English names for the resource, e.g. `/roles` and `/hosts`. Collections support the following operations:
|
||||
|
||||
- Creation of new resources within that collection
|
||||
- Listing of resources within that collection
|
||||
|
||||
All collection operations require supplying the enclosing resource. Depending on the collection type, this will be one of the following:
|
||||
|
||||
- A scope, indicating the scope in which an operation should take place. For instance, a POST to `/roles` would need to indicate whether the role should be created within the `global` scope or an org-level scope like `o_1234567890`.
|
||||
- A parent resource of the appropriate type. For instance, hosts and host sets are child resources of host catalogs. When creating a new host set within a host catalog, a POST to `/host-sets` would need to indicate the host catalog ID with which the host-set should be associated.
|
||||
|
||||
### Resources
|
||||
|
||||
Resources themselves are defined by ID specifiers within a collection path, e.g. `/roles/r_1234567890`. Resources support the following operations:
|
||||
|
||||
- Reading a resource's properties
|
||||
- Updating a resource's properties
|
||||
- Deleting a resource
|
||||
- Custom methods specific to a resource type
|
||||
|
||||
Depending on the resource type, various parameters may be available. Some are common across all resource types (e.g. `name` and `description`); others are available only for specific types. Further, some concrete-types of abstract resources include an opaque `attributes` JSON object with type-specific values.
|
||||
|
||||
For instance, an auth method is an abstract type; a `password` auth method is a concrete implementation of that type. When creating such an auth method, a `type` parameter will indicate that it should be the `password` type, while values specific to the `password` type auth method, such as minimum password length, will be contained within an `attributes` object.
|
||||
|
||||
## Methods
|
||||
|
||||
The following method conventions are used within Boundary's API:
|
||||
|
||||
### GET
|
||||
|
||||
`GET` is used for reading a resource or listing resources in a collection. The behavior depends on whether the `GET` is issued against a collection (`/roles`) or a singular resource (`/roles/r_1234567890`). In the former case it lists resources within the collection; in the latter it performs a read on that particular resource.
|
||||
|
||||
### POST
|
||||
|
||||
`POST` is used for creating a resource or performing custom actions against a resource. When creating a resource, `POST` is used against a collection (`/roles`). When performing a custom action, `POST` is used against a particular resource (`/roles/r_1234567890:set-principals`).
|
||||
|
||||
### PATCH
|
||||
|
||||
`PATCH` is used to update a resource's parameters. The following are behaviors to be aware of when using `PATCH`:
|
||||
|
||||
- In nearly all cases, a `version` parameter is required. This is used for check-and-set, to ensure that the update operation is being performed against a known resource. The version parameter is returned from a `GET` operation on the resource so the current version, along with the resource's other current values, can be looked up at any time.
|
||||
- Passing a JSON `null` for a parameter has the effect of reverting that parameter to its default. For some parameters (e.g. `name`) this will simply clear the value (as the default `name` for a resource is empty); for other parameters this will revert to the current defaults within Boundary.
|
||||
- All parameters specified as part of a `PATCH` operation will be considered to be parameters that should be updated.
|
||||
|
||||
### DELETE
|
||||
|
||||
`DELETE` is used for deleting a specific resource, and is only used against a particular resource path.
|
||||
|
||||
## HTTP headers
|
||||
|
||||
Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage.
|
||||
Responses may contain the following headers:
|
||||
|
||||
- `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action.
|
||||
- `RateLimit-Policy` - Describes the limits for the requested resource and action.
|
||||
- `X-Correlation-ID` - Identifies a transaction over a series of requests and responses.
|
||||
The `X-Correlation-ID` header is a universally unique identifier (UUIDv4).
|
||||
If you provide an `X-Correlation-ID` header in an HTTP request, Boundary logs that value for all audit events related to the request.
|
||||
It then uses that value as the header when it makes related requests to an external system, such as Vault, so that you can correlate the event between the product logs.
|
||||
If you do not provide an `X-Correlation-ID` header, Boundary generates a unique value for each incoming request.
|
||||
|
||||
## Manage system resources
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: API list pagination
|
||||
description: >-
|
||||
Learn about API pagination and how the cache works in Boundary to prevent system resources from being overwhelmed and to help you find resources.
|
||||
---
|
||||
|
||||
# API list pagination
|
||||
|
||||
Boundary uses an API pagination feature to support searching and filtering large lists of results without overwhelming your system resources.
|
||||
|
||||
## Introduction
|
||||
|
||||
When you perform a `list` operation on a resource, the API request returns the first 1000 results, by default.
|
||||
You can request the next page of results by repeating the `list` command and including a parameter with a token provided by Boundary.
|
||||
|
||||
## Initial pagination
|
||||
|
||||
When you run a `list` operation on a resource, the initial results are sorted in descending order by creation time and public ID (most recently created first).
|
||||
Boundary returns the maximum number of responses along with the top-level fields `response_type` and `list_token`.
|
||||
If the `response_type` is `delta`, it means there are more items available in the list.
|
||||
|
||||
List tokens contain general metadata associated with the ongoing pagination.
|
||||
To request the next page of results, run the `list` operation again and include the `list_token` that Boundary provided in the last response.
|
||||
Boundary returns the next page of results with new `response_type` and `list_token` values.
|
||||
|
||||

|
||||
|
||||
You can continue viewing new pages of results using the `list_token` values until the `response_type` reads `complete`.
|
||||
If you compose an invalid token, you receive an invalid token error.
|
||||
|
||||
## Request updated and deleted resources
|
||||
|
||||
When the `response_type` reads `complete`, you have viewed all the results that were available when you ran the initial `list` operation.
|
||||
You can now request any resources that were updated or deleted since you started paginating.
|
||||
|
||||
To refresh the cached list results, make another `list` request using the `list_token` from the previous response.
|
||||
Boundary returns a `response_type` and `list_token` as part of the response, similarly to when you ran the initial operation.
|
||||
If the `response_type` is `delta`, it means there are more items available in the list.
|
||||
You can use the `list_token` as a parameter to continue viewing new pages of results until the `response_type` reads `complete`.
|
||||
|
||||
Boundary also includes the top-level response `removed_ids` as part of the refresh operation.
|
||||
The `removed_ids` response contains the IDs of any resources that were deleted since you began paginating the results of the previous `list` operation.
|
||||
Any resources that have been deleted are included on the first page of results.
|
||||
|
||||
After 30 days, the `list_token` expires and you must make a new `list` request without the token to regenerate the full list of results.
|
||||
If you make a `list` request using a token that has a `create_time` older than 30 days, Boundary treats it as an invalid token and returns an error.
|
||||
|
||||
## Response structure
|
||||
|
||||
All `list` endpoints support the following parameters:
|
||||
|
||||
- `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.
|
||||
If you do not include a value, or if you include a value of `0`, Boundary uses the default page size of 1000 items.
|
||||
If you configure it, the `page_size` value overrides the default page size.
|
||||
Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request.
|
||||
|
||||
Boundary returns the following response parameters:
|
||||
|
||||
- `response_type` - Defines whether the response is a `delta` or `complete` listing.
|
||||
The value is `delta` until the last page is returned, at which point it will be `complete`.
|
||||
- `list_token` - An opaque token which is included in subsequent listing requests after the initial one, so that the client can continue to paginate the results.
|
||||
- `sort_by` - The column name that the returned items should be sorted on.
|
||||
This attribute is included in the response, so that the sort order for each endpoint is explicit.
|
||||
- `sort_dir` - The direction in which the returned items are sorted.
|
||||
Responses can include `desc` for descending, or `asc` for ascending.
|
||||
- `items` - The list of items.
|
||||
- `est_item_count` - An unsigned integer that indicates the total number of items that are available in the list of results.
|
||||
This number may be an estimate, since the number of items may change during the pagination process.
|
||||
|
||||
### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"response_type": "<delta|complete>",
|
||||
"list_token": "<opaque-token>",
|
||||
"sort_by": "created_time",
|
||||
"sort_dir": "desc",
|
||||
"est_item_count": 1000,
|
||||
"items": [
|
||||
{
|
||||
"id": "ttcp_1234567890",
|
||||
"scope_id": "p_1234567890"
|
||||
},
|
||||
{
|
||||
"id": "ttcp_2234567890",
|
||||
"scope_id": "p_1234567890"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Constraints and limitations
|
||||
|
||||
In scenarios where updates are so frequent that the results may change while the refresh operation runs, those updates may not appear at all in the refreshed list.
|
||||
If you make frequent updates to a resource, or if you are updating data while you run a `list` operation, HashiCorp recommends that you generate the full list of results instead of performing a refresh.
|
||||
|
||||
Workers are not included in refresh operations because the updates they send to the controller are too frequent to be captured in a refresh.
|
||||
To update a list of worker resources, you must regenerate the full list of results.
|
||||
|
||||
When you refresh the list of results, you may notice duplicate items in the list.
|
||||
This is a fundamental tradeoff when you search across multiple database transactions.
|
||||
@@ -1,199 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: API rate limiting
|
||||
description: >-
|
||||
Learn how API rate limiting lets you configure limits on the rates of API requests in Boundary to help manage resources and prevent them from being overwhelmed.
|
||||
---
|
||||
|
||||
# Rate limiting
|
||||
|
||||
If your controllers try to process every API request, it can lead to situations when the controllers are overwhelmed with requests.
|
||||
The controllers may either run out of resources or overwhelm the database server and exhaust its resources.
|
||||
API rate limiting lets you configure limits on the rate of API requests to help manage your resources and prevent them from being overwhelmed.
|
||||
|
||||
## Quotas
|
||||
|
||||
Boundary creates quotas to track the number of requests in a given time period.
|
||||
By default, Boundary tracks the number of requests by auth token, IP address, and the overall total.
|
||||
Boundary reserves a portion of its memory for tracking quotas to ensure that it does not consume too much memory if there is a sudden burst of requests.
|
||||
|
||||
If Boundary is unable to store a quota, it limits the request with a 503 HTTP status code.
|
||||
You can configure the maximum number of quotas Boundary allows using the `api_rate_limit_max_quotas` variable.
|
||||
There are also two metrics that allow you to monitor quota tracking:
|
||||
|
||||
- `boundary_controller_api_ratelimiter_quota_storage_capacity`
|
||||
- `boundary_controller_api_ratelimiter_quota_storage_usage`
|
||||
|
||||
## Default limits
|
||||
|
||||
API rate limiting is enforced on the controllers.
|
||||
There are separate configurable limits for each combination of resource and action.
|
||||
By default, the limits for `list` actions are:
|
||||
|
||||
- 150 requests per 30 seconds per auth token
|
||||
- 1,500 requests per 30 seconds per IP address
|
||||
- 1,500 requests per 30 seconds in total
|
||||
|
||||
The default limits for all other actions are:
|
||||
|
||||
- 3,000 requests per 30 seconds per auth token
|
||||
- 30,000 requests per 30 seconds per IP address
|
||||
- 30,000 requests per 30 seconds in total
|
||||
|
||||
You can override the default settings and configure other specific limitations using the `api_rate_limit` stanza in the controller configuration.
|
||||
|
||||
## Rate limiting HTTP headers
|
||||
|
||||
Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage.
|
||||
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).
|
||||
|
||||
## More information
|
||||
|
||||
Refer to the [controller stanza](/boundary/docs/configuration/controller#api_rate_limit) documentation for the specific `api_rate_limit` configuration options.
|
||||
Some example configurations are listed below.
|
||||
|
||||
### Rate limiting configuration examples
|
||||
|
||||
The following example shows a simple configuration where the same limits are applied to all resources and examples:
|
||||
|
||||
```hcl
|
||||
controller {
|
||||
# Total limit for all resources and actions
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "total"
|
||||
limit = 500
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit for all IP addresses to all resources and actions to prevent a
|
||||
# malicious host that is fabricating tokens or spamming unauthed endpoints
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "ip-address"
|
||||
limit = 100
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit for all authed requests to prevent one user
|
||||
# from consuming all of the total limit
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "auth-token"
|
||||
limit = 100
|
||||
period = "1s"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following example shows a configuration that disables rate limiting.
|
||||
You may want to disable rate limiting if you already use an external system like a reverse proxy to apply rate limiting:
|
||||
|
||||
```hcl
|
||||
controller {
|
||||
api_rate_limit_disable = true
|
||||
}
|
||||
```
|
||||
|
||||
The following example uses the default settings for most endpoints, but configures a single override:
|
||||
|
||||
```hcl
|
||||
controller {
|
||||
api_rate_limit {
|
||||
resources = ["target"]
|
||||
actions = ["list"]
|
||||
per = "auth-token"
|
||||
limit = 10
|
||||
period = "1s"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following example is more complex.
|
||||
Initially it sets some defaults to apply to all resources and actions.
|
||||
Then it configures some specific endpoints with different limits.
|
||||
|
||||
```hcl
|
||||
controller {
|
||||
# Total limit for all resources and actions
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "total"
|
||||
limit = 500
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Total limit for all list operations,
|
||||
# sets an overall cap on the list action since it is relatively expensive
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["list"]
|
||||
per = "total"
|
||||
limit = 200
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit for IP address to all resources and actions
|
||||
# to prevent a malicious host that is fabricating tokens
|
||||
# or spamming unauthed endpoints
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "ip-address"
|
||||
limit = 50
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit of all authed requests, this essentially sets a default
|
||||
# for all authed requests to prevent one user from consuming
|
||||
# all of the total list limit set above. Any limits that follow
|
||||
# can override the default for specific sets of resources and actions
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["*"]
|
||||
per = "auth-token"
|
||||
limit = 100
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit of all list operations by auth token to set a sane default
|
||||
# since they are generally more expensive
|
||||
api_rate_limit {
|
||||
resources = ["*"]
|
||||
actions = ["list"]
|
||||
per = "auth-token"
|
||||
limit = 50
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
# Limit for targets and sessions list by auth token. These are resources
|
||||
# that clients will want to list frequently, but might be more expensive
|
||||
# if there is a large number of them for each user. Having a lower limit
|
||||
# encourages the use of refresh tokens and caching.
|
||||
api_rate_limit {
|
||||
resources = ["target", "session"]
|
||||
actions = ["list"]
|
||||
per = "auth-token"
|
||||
limit = 20
|
||||
period = "1s"
|
||||
}
|
||||
|
||||
#Limit for authorize session by auth token
|
||||
api_rate_limit {
|
||||
resources = ["target"]
|
||||
actions = ["authorize-session"]
|
||||
per = "auth-token"
|
||||
limit = 150
|
||||
period = "1s"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -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)
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Client cache overview
|
||||
description: >-
|
||||
Learn how the client cache enables Boundary to quickly retrieve local information about session and target resources. Manage startup and other cache functions.
|
||||
---
|
||||
|
||||
# Client cache
|
||||
|
||||
The Boundary client cache runs on end users' computers and locally caches session and target resource information from Boundary instances.
|
||||
The cache helps expedite searches.
|
||||
|
||||
## Boundary `list` vs. `search`
|
||||
|
||||
You can use the Boundary API or CLI to `list` resources like targets, sessions, hosts, and users.
|
||||
When you use the `list` command, Boundary searches the control plane to provide a current total of resources when it produces the list of results.
|
||||
Some Boundary resources can provide a significant number of items in the response.
|
||||
|
||||
Because large lists of results may overwhelm your system resources, the client cache caches the results of the `list` operation.
|
||||
You can search the local cache instead of the control plane to help protect your system resources.
|
||||
The Boundary `search` command also produces a list of Boundary resources.
|
||||
When you use the `search` command, however, Boundary searches the local cache to create the list.
|
||||
|
||||
For more information, refer to the [`search`](/boundary/docs/commands/search) command documentation.
|
||||
|
||||
<Note>
|
||||
|
||||
The `search` operation only displays the resources that you have read permissions to view.
|
||||
If you are logged in as a user who does not have the permissions to view a resource, it does not display in the list of results.
|
||||
|
||||
For more information, refer to [Identity and access management (IAM)](/boundary/docs/concepts/iam).
|
||||
|
||||
</Note>
|
||||
|
||||
## Client cache management
|
||||
|
||||
The Boundary client cache starts automatically in the background when a user runs a CLI command that interacts with a Boundary instance.
|
||||
If you do not want the cache to automatically start, you can include the `-skip-cache-daemon` flag or set the **BOUNDARY_SKIP_CACHE_DAEMON** environment variable when you use the Boundary CLI to interact with a Boundary instance.
|
||||
|
||||
### Startup and customization
|
||||
|
||||
You can start the cache manually using the `boundary cache start` command.
|
||||
By default, the cache starts in the foreground.
|
||||
You can start it in the background by adding the `-background` flag.
|
||||
|
||||
If you start the cache manually, you can customize the caching behavior.
|
||||
Include any of the following options to customize the behavior:
|
||||
|
||||
- `max-search-staleness` - The amount of time that can pass since the last refresh before calling `boundary search` results in a blocking refresh from the Boundary instance of the resources being searched.
|
||||
- `max-search-refresh-timeout` - The amount of time the `boundary search` blocking refresh can take before it times out.
|
||||
In the event of a timeout, Boundary uses the stale data that is currently in the cache.
|
||||
- `refresh-interval` - A duration that specifies how frequently the client cache should query Boundary for changes to sessions and targets.
|
||||
Note that Boundary only searches sessions and targets that the user who ran the command has access to.
|
||||
|
||||
For more information, refer to the [`cache start`](/boundary/docs/commands/cache/start) command documentation.
|
||||
|
||||
### Logging
|
||||
|
||||
The client cache stores a log file in the **~/.boundary** directory.
|
||||
Boundary automatically rotates the log once it reaches 5 MB.
|
||||
It compresses and keeps the last 3 rotated logs before deleting a log.
|
||||
|
||||
### Status
|
||||
|
||||
You can check the status of the cache using the `boundary cache status` command.
|
||||
The command returns information about the cache including the uptime, user count, user information, and which Boundary resources the cache is tracking.
|
||||
|
||||
For more information, refer to the [`cache status`](/boundary/docs/commands/cache/status) command documentation.
|
||||
|
||||
|
||||
### Auth tokens
|
||||
|
||||
By default, the Boundary CLI tries to use a keyring to store and receive auth tokens.
|
||||
Whenever you use an auth token to interact with Boundary, the client cache stores the auth token and syncs the data associated with it.
|
||||
If you authenticate to multiple Boundary instances, the client cache stores multiple auth tokens and syncs the data associated with each token.
|
||||
|
||||
To search the client cache for a specific Boundary instance, you can specify the appropriate auth token using the `boundary cache add-token` command.
|
||||
|
||||
For more information, refer to the [`cache add-token`](/boundary/docs/commands/cache/add-token) command documentation.
|
||||
@@ -1,215 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Go SDK overview
|
||||
description: >-
|
||||
Learn about Boundary's Go SDK. Use the Go SDK to authenticate to Boundary with an auth method or a recovery KMS workflow.
|
||||
---
|
||||
|
||||
# Go SDK
|
||||
|
||||
Boundary has a Go SDK that sports full coverage of Boundary's API. This SDK is mostly auto-generated, so the patterns are predictable from package to package. For the most part, browsing [pkg.go.dev](https://pkg.go.dev/github.com/hashicorp/boundary/api) is a great way to get started.
|
||||
|
||||
<Note>
|
||||
|
||||
The Boundary API is configured with [rate limiting](/boundary/docs/api-clients/api#rate-limiting), by default.
|
||||
If the Boundary SDK client is unable to process a request due to a rate limit being met, it sends the API a `429` or `523` [status code](/boundary/docs/api-clients/api#status-codes) and limits the request.
|
||||
By default the client will wait for the amount of time specified in the `Retry-After` header and then try again for a maximum of 2 retries.
|
||||
|
||||
</Note>
|
||||
|
||||
Below, an example walks through using the SDK to authenticate against an auth method or perform recovery workflows. The patterns for creating a resource-typed client are the same across packages.
|
||||
|
||||
## Authenticating to Boundary with the Go SDK
|
||||
|
||||
Authenticating to Boundary starts with an [Auth Method](/boundary/docs/concepts/domain-model/auth-methods). An auth method provides
|
||||
the basic identity delegation needed for Boundary to generate a token for a client. There are two primary methods for
|
||||
authenticating to Boundary:
|
||||
|
||||
1. Via an auth method
|
||||
1. Via the recovery KMS workflow
|
||||
|
||||
We'll cover how to authenticate to Boundary via both of these workflows.
|
||||
|
||||
### Auth method
|
||||
|
||||
This is the most common way for a client to authenticate to Boundary. To demonstrate this, we'll
|
||||
use the [authmethods](https://github.com/hashicorp/boundary/tree/main/api/authmethods) library to generate
|
||||
a valid token for a client in Go.
|
||||
|
||||
For this example, we're going to use the [password auth method](/boundary/docs/concepts/domain-model/auth-methods#password-auth-method-attributes). This example
|
||||
assumes there's already a valid user and an associated account in Boundary
|
||||
against which the client can authenticate. To simplify this example, we're
|
||||
assuming you're running a Boundary instance in dev mode, where the default auth
|
||||
method, login name, and password are pre-configured.
|
||||
|
||||
First, we need to create a client from the Boundary API and set the address to reach Boundary:
|
||||
|
||||
```go
|
||||
// The default address points to the default dev mode address
|
||||
client, err := api.NewClient(nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
The [authenticate
|
||||
method](https://github.com/hashicorp/boundary/blob/main/api/authmethods/authenticate.go)
|
||||
uses a basic `map[string]interface{}` to pass credential information, in order
|
||||
to eventually support multiple auth method types. For this example, we assume
|
||||
you're using the password auth method, and so we create an attributes
|
||||
map to pass this data:
|
||||
|
||||
```go
|
||||
credentials := map[string]interface{}{
|
||||
"login_name": "admin",
|
||||
"password": "password",
|
||||
}
|
||||
```
|
||||
|
||||
Now let's create an auth method client using the base client from above:
|
||||
|
||||
```go
|
||||
amClient := authmethods.NewClient(client)
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
This creates a shallow copy of the base client. Modifications made to the client via `am.ApiClient()` will not be reflected in the base client.
|
||||
|
||||
</Note>
|
||||
|
||||
The last thing you'll need is the ID of the auth method in Boundary. You can get this on the CLI
|
||||
with:
|
||||
|
||||
```bash
|
||||
$ boundary auth-methods list
|
||||
|
||||
Auth Method information:
|
||||
ID: ampw_1234567890
|
||||
Description: Provides initial administrative authentication into Boundary
|
||||
Name: Generated global scope initial auth method
|
||||
Type: password
|
||||
Version: 1
|
||||
```
|
||||
|
||||
Note the ID in the output above, we're going to use that in the next step.
|
||||
|
||||
We can use the credentials object we created to execute `Authenticate()` on this client:
|
||||
|
||||
```go
|
||||
authenticationResult, err := amClient.Authenticate(context.Background(), "ampw_1234567890", "login", credentials)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
Lastly, let's update the original client with the token we got from the `Authenticate()` call:
|
||||
|
||||
```go
|
||||
// pass this client to any other resource specific API resources
|
||||
client.SetToken(fmt.Sprint(authenticationResult.Attributes["token"]))
|
||||
```
|
||||
|
||||
Putting this all together:
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/hashicorp/boundary/api"
|
||||
"github.com/hashicorp/boundary/api/authmethods"
|
||||
)
|
||||
|
||||
credentials := map[string]interface{}{
|
||||
"login_name": "admin",
|
||||
"password": "password",
|
||||
}
|
||||
|
||||
// The default address points to the default dev mode address
|
||||
client, err := api.NewClient(nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
amClient := authmethods.NewClient(client)
|
||||
authenticationResult, err := amClient.Authenticate(context.Background(), "ampw_1234567890", "login", credentials)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// pass this client to any other resource specific API resources
|
||||
client.SetToken(fmt.Sprint(authenticationResult.Attributes["token"]))
|
||||
```
|
||||
|
||||
### Recovery KMS workflow
|
||||
|
||||
The recovery KMS workflow allows you to use a valid [KMS
|
||||
configuration](/boundary/docs/configuration/kms) to authenticate and authorize calls
|
||||
within the Boundary API. For this example, we're going to assume you've read the
|
||||
above and know how to get a base Boundary API client.
|
||||
|
||||
Lets start with a valid KMS configuration for recovery that uses a hard coded
|
||||
AEAD key as the basis. To authenticate with Boundary using this config we're
|
||||
assuming you have an instance of Boundary that declares this as the recovery KMS
|
||||
in the Boundary controller config as well.
|
||||
|
||||
```go
|
||||
import "github.com/hashicorp/boundary/sdk/wrapper"
|
||||
|
||||
const kmsConfig = `
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "recovery_kms"
|
||||
}
|
||||
`
|
||||
```
|
||||
|
||||
Now lets use this config to configure our Boundary API client:
|
||||
|
||||
```go
|
||||
w, err := wrapper.GetWrapperFromHcl(kmsConfig, "recovery")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
client.SetRecoveryKmsWrapper(w)
|
||||
```
|
||||
|
||||
The client will now use the recovery KMS wrapper for all authenticated calls
|
||||
(even if you have previously set a token). You can remove it by instantiating a
|
||||
new client, or by passing `nil` into `SetRecoveryKmsWrapper`.
|
||||
|
||||
Putting this all together:
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/hashicorp/boundary/api"
|
||||
"github.com/hashicorp/boundary/sdk/wrapper"
|
||||
)
|
||||
|
||||
const kmsConfig = `
|
||||
kms "aead" {
|
||||
purpose = "recovery"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "recovery_kms"
|
||||
}
|
||||
`
|
||||
|
||||
// The default address points to the default dev mode address
|
||||
client, err := api.NewClient(nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
w, err := wrapper.GetWrapperFromHcl(kmsConfig, "recovery")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
client.SetRecoveryKmsWrapper(w)
|
||||
```
|
||||
Reference in new issue
Block a user