macOS Agent Troubleshooting

Update the Agent

Before performing any troubleshooting steps, please be sure you have the latest version of the Agent.

How to check if you have the latest version of the Agent:

1. Navigate to the UI

   1. Then go to Settings>Protect Agent

   2. From the “Install” screen, you’ll see the “Install Download” buttons. These buttons have the latest release number on them. Note the release number for the Windows Agent here.

Now, there are two quick ways to find out which version is on your machine.

• Navigate to the “Manage Agents” section of the HPA Dashboard.

  1. From there, find your machine name, and scroll over to see it’s associated version.

  2. Navigate back to your mac machine.

  3. Right-click on the HYAS Protect icon in the menu bar and you’ll see the version number at the bottom of the window.

• If you Agent version is outdated, please follow the Uninstall directions listed above and install the latest version.

Debug Mode

In all cases where it is suspected that the HYAS agent may be encountering an issue or may be the cause of connectivity issues it is highly recommended to enable debug logging for the HPA to capture verbose telemetry to expedite troubleshooting.

• To enable Debug mode, refer to the Agent Preferences section above.

• From there, Client Admins or HYAS can review the logs located at

  • macintosh HD/private/var/log/com.hyas.protect

Captive Portal Connectivity

Issue

When connecting to the Internet via a hotel, coffee shop, or related location, often the store or location utilizes a “captive portal” that the device must connect to prior to obtaining full Internet access. In some cases, the device may not properly connect to the captive portal, meaning that the device may not properly authenticate to obtain access to the Internet.

Solution

First – the user should perform a restart of their device. A device reboot should resolve the issue; if it does not, please perform the steps below.

If a reboot does not resolve the issue, and the device still cannot connect to the captive portal, you need to stop the Protect service (please note the user will need admin privileges to perform these steps)

• To stop the HPA, follow the above recommended method and stop the service via Terminal.

The device should now be able to connect to the captive portal and thus the Internet.  If the captive portal does not appear, consider disconnecting from the network and reconnect to prompt the captive portal to appear, or reboot the machine.

When network access has been restored, restart the Protect service using the procedure referenced above.

If the above suggestions are ineffective and immediate access to the network is required, the agent may be disabled via the following procedure:

• Connect temporarily to another network such as personal cellular hotspot

  • Coordinate with IT to allow an admin to remotely access the machine

  • Admin runs a disable script provided by HYAS

  • When the agent has been disabled, disconnect from the hotspot or other network

  • Reconnect to the network with the captive portal (may require machine reboot)

Local Domains Not Resolving

Issue

Unable to resolve local domains.

Solution

Corporate networks, often referred to as a corporate or company Intranet, typically use local domains (DNS suffixes) for local resources. If a problem with the resolution of local domains occurs:

• Ensure all local domains associated with the organization are configured in the Local Domains tab in the HYAS Protect UI.

  • This can be found under Settings > Protect Agent

• If a local domain is not configured, then endpoints will not be able to resolve resources associated with that domain. 

• Configure any internal resolver IP in the HYAS Protect UI that is expecting an endpoint to query for DNS records. This should be completed prior to the agent installation to prevent possible resolution issues and negative user experience.

Split-Brain/DNS Functionality

Issue

In some cases, organizations use of the same domain both on the local intranet and on the internet. This dual usage creates ambiguity in resolving the domain's IP address, as it may resolve to private IP addresses when connected to the intranet and to public IP addresses when outside the office.

Solution

In determining network location, the HYAS Protect Agent distinguishes between local and external networks. If it detects the local network, it routes DNS requests to local resolvers based on defined settings. Otherwise, it directs queries to HYAS Protect cloud resolvers. The HYAS Protect web portal facilitates configuring specific DNS queries and their expected outcomes. The agent then periodically runs these tests to differentiate internal from external requests. Note that versions of the agent before 2.2.1 lack Split Brain DNS functionality and may not function properly in such scenarios. Upgrade to version 2.2.1 or above for optimal performance. Find the latest agent version in the UI under Settings > Protect Agent > Install. Click here to learn more about configuring Split-Brain DNS

HYAS Icon shows not protected when all HYAS services are active and green

Issue

For Agent versions 2.2.1 and older, there is a know issue where the HYAS icon in the Menu Bar indicates that the HPA service is not currently active on the machine.

Solution

The solution here is to update the Agent. In absence of that, right-click on the HYAS icon in the Menu Bar. If all four checks (Protected, Internet Check, OS Check & DNS Proxy Check) all show green, then the service is fully functional and protecting the machine.

Block Page Issues

Issue

For Agent versions 2.2.1 and older, users may experience a block page error when trying to access a blocked domain.

Solution

The solution here is to update the Agent to the latest version. The latest versions of the Agent include the HYAS Root Certificate Authority as part of the installation package.

Additional Troubleshooting Scripts for Terminal

Note that Administrator privileges are needed in order to run the below scripts.

View Local Log

sudo tail -f /var/log/com.hyas.protect/dnsproxy.log

Uninstall

sudo bash /Library/Application\ Support/com.hyas.protect/uninstall.sh
rm /tmp/.hyas.protect.client.id 

Check Running State

ps -ef | grep com.hyas.protect.dnsproxy | grep -v grep
sudo launchctl list | grep hyas
ps -ef | grep "HYAS Protect.app" | grep -v grep

Restart the Service

sudo launchctl unload /Library/LaunchDaemons/com.hyas.protect.plist
sleep 3
sudo launchctl load /Library/LaunchDaemons/com.hyas.protect.plist

Stop Service

sudo launchctl unload /Library/LaunchDaemons/com.hyas.protect.plist

Start Service

sudo launchctl load /Library/LaunchDaemons/com.hyas.protect.plist