From cfddc2c12b2e152cb13784d7efcca50014c8d1d9 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 22 Apr 2025 13:46:23 -0400 Subject: [PATCH] docs: Document OpenVPN DNS conflict --- .../content/docs/api-clients/client-agent.mdx | 125 +++++++++++++----- 1 file changed, 94 insertions(+), 31 deletions(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index 8612c80a7a..46075d0598 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -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 +] +``` + + + +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. + + + +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 -### 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