From 84a056eb0a8323b9e263d592885cd15c134f4bb3 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 22 Apr 2025 17:46:23 +0000 Subject: [PATCH 1/6] backport of commit cfddc2c12b2e152cb13784d7efcca50014c8d1d9 --- .../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 9814ed4c00..bad8f477c9 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -546,21 +546,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 @@ -659,34 +743,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 From 157a1d10c5155b6c6f87d2ce2f82262fea6f502d Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 22 Apr 2025 17:49:10 +0000 Subject: [PATCH 2/6] backport of commit 97abab4b309e0fbc72f67722676c1592a1ccca9c --- website/content/docs/api-clients/client-agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index bad8f477c9..4da0064b97 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -619,14 +619,14 @@ 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. +When you run the Client Agent alongside OpenVPN on MacOS, the primary network interface will likely be set to a `utun` 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: +To work around the default `utun` interface, you must provide an explicit network interface using the `interface_to_use` configuration option. For example: ```hcl interface_to_use=en0 From efe877bd546a83c026c98c7877f2da78054624d2 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Wed, 23 Apr 2025 15:00:59 +0000 Subject: [PATCH 3/6] backport of commit 7bfe697483c2f75d1ec30a6c7b6edb8b87aa17b9 --- .../content/docs/api-clients/client-agent.mdx | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index 4da0064b97..f20738aced 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -541,6 +541,26 @@ $ 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. @@ -562,7 +582,8 @@ 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. +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) From 7f152a28bee3ad84fe149a71d182817167f57c7e Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Thu, 24 Apr 2025 20:18:27 +0000 Subject: [PATCH 4/6] backport of commit fe13a7b0b95553e2ee43253fbe4a54c8fbf474bb --- .../content/docs/api-clients/client-agent.mdx | 31 +++++-------------- 1 file changed, 8 insertions(+), 23 deletions(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index f20738aced..7f7c505610 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -635,37 +635,22 @@ If you only provide the VPN DNS servers, the Client Agent will not be able to re -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. +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 you run the Client Agent alongside OpenVPN on MacOS, the primary network interface will likely be set to a `utun` 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 `utun` 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. +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 -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. +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 From 41eeb55a17436f87b172d22f82387aab0fe99431 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Fri, 2 May 2025 15:20:47 +0000 Subject: [PATCH 5/6] backport of commit 9aa30efb0f2ba54457174bea7c005e4203df3971 --- website/content/docs/api-clients/client-agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index 7f7c505610..f948d792df 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -461,9 +461,9 @@ After you flush the DNS cache, try connecting to the alias again, or repeat the 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. -### Commonly seen errors +### Common error messages -Refer to the following commonly seen errors for more information about their possible causes and resolutions. +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 From 4a3e3ebb39865072d4c7d3171294626f294c6ec0 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Fri, 2 May 2025 16:07:23 +0000 Subject: [PATCH 6/6] backport of commit 9ff8657c8e1f48c3791a46b14ff8427333abe2b8 --- website/content/docs/api-clients/client-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx index f948d792df..a1c491d557 100644 --- a/website/content/docs/api-clients/client-agent.mdx +++ b/website/content/docs/api-clients/client-agent.mdx @@ -334,7 +334,7 @@ If not, you may need to first authenticate to the Client Agent using the CLI or 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 commonly seen errors to help diagnose specific errors. +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.