Dan HeathandRobin Beck
5ce6515156
* 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>
159 lines
4.6 KiB
Plaintext
159 lines
4.6 KiB
Plaintext
---
|
|
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> |