aherman
/
boundary
mirror of https://github.com/hashicorp/boundary
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Document OpenVPN DNS conflict

Browse Source
pull/5674/head
Dan Heath 1 year ago
parent 32d139c45e
commit cfddc2c12b
1 changed files with 94 additions and 31 deletions
Show Stats Download Patch File Download Diff File

125
website/content/docs/api-clients/client-agent.mdx
Unescape View File

@ -540,21 +540,105 @@ You can also remove the existing server host key from the `~/.ssh/known_hosts` f
Some software is known to cause conflicts 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.
As long as you don't run both at the same time, they should work as expected.
### 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.
### 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.
### OpenVPN
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.
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 are using OpenVPN's DNS settings, it may create additional conflicts.
Refer to the steps below for possible workarounds for MacOS and Windows.
#### MacOS
When you run the Client Agent alongside OpenVPN on MacOS, 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.
If both OpenVPN and the Client Agent are configured to listen for changes to the primary DNS, each service may attempt to override the other's DNS settings.
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
If both OpenVPN and the Client Agent are configured to listen for changes to the primary DNS, each service may attempt to override the other's DNS settings.
OpenVPN creates a `DNSClientNrptRule` that prevents the Client Agent from establishing itself as the primary DNS resolver.
As a workaround, you can manually delete all `DNSClientNrptRule` entries and override the DNS settings for the Local Area Connection.
### Palo Alto Networking Global Protect VPN
@ -653,34 +737,13 @@ You must restart the Client Agent for it to update its configuration with the ne
</Tab>
</Tabs>
### 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.
As long as you don't run both at the same time, they should work as expected.
### Huntress EDR client
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.
### Parallels Desktop (MacOS VM on MacOS Host)
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.
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.
This issue does not affect macOS devices, where Boundary and Huntress coexist without additional configuration.
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

Write Preview
Loading…
Cancel
Save