mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
238 lines
12 KiB
238 lines
12 KiB
---
|
|
layout: docs
|
|
page_title: Client Agent conflicting software
|
|
description: >-
|
|
Learn how possible conflicts that third-party tools may have with the Boundary Client Agent. Explore possible solutions and workarounds.
|
|
---
|
|
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
|
|
# Client Agent software conflicts
|
|
|
|
Some software is known to cause conflicts with the Boundary Client Agent.
|
|
Refer to the [transparent sessions interoperability matrix](/boundary/docs/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.
|
|
|
|
## Cisco AnyConnect VPN
|
|
|
|
When the Cisco AnyConnect VPN is active at the same time as the Boundary Client Agent, DNS resolution may fail for Boundary aliases.
|
|
|
|
The Boundary Client Agent by default uses the IPv4 range `100.x.x.x` for its local proxies. The Cisco AnyConnect VPN treats this range as a **secured range**, which forces DNS queries to resolve through the VPN instead of the Boundary Client Agent. As a result, Boundary aliases cannot be resolved.
|
|
|
|
You can configure the Boundary Client Agent to use a different IPv4 prefix by setting the `v4_prefix` option in the client configuration file. This setting overrides the default `100.x.x.x` range and avoids the conflict with Cisco AnyConnect VPN.
|
|
|
|
For example:
|
|
```hcl
|
|
v4_prefix = "172.16.0.0/12"
|
|
```
|
|
<Note>
|
|
|
|
You can set the `v4_prefix` to any valid RFC1918 private IPv4 range, as long as it does not overlap with ranges secured by the VPN. Common options include:
|
|
|
|
- `10.0.0.0/8`
|
|
- `172.16.0.0/12`
|
|
|
|
Choose a range that best fits your environment.
|
|
|
|
</Note>
|
|
|
|
## 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.
|