Windows

Overview

The HYAS Protect Agent (HPA) empowers organizations to leverage the robust capabilities of HYAS Protect on their roaming devices. Functioning as a DNS Proxy, the HPA offers a straightforward, lightweight, and highly effective solution to extend the full benefits of HYAS Protect to your mobile workforce.

This page will review the HPA installation procedure for a Windows machine. We’ll give you both UI and PowerShell options along with some troubleshooting steps if you get stuck along the way.

Architecture

• The HPA consists of two parts, a service and a UI (user interface)

  • Service/Backend: The service, also known as the backend, is responsible for the core functionality and logic of the Agent.

  • The UI, also known as the front end, is the part of the application that users interact with.

• For purposes of this document, when referring to the HPA, we mean the service and the UI together.

Agent Deployment

If your organization uses local domains, please be sure to configure Local Domains PRIOR to deploying the HPA.

If your organization uses a VPN, please review VPN compatibility testing below PRIOR to deploying the HPA.

Downloading the Agent - HYAS Protect UI

HYAS makes it simple to download the Windows HPA directly through the UI.

1. Log into the HYAS Protect UI.

2. Navigate to the Settings icon

3. Select ‘Organization Settings’

   1. 

4. Finally, select 'Protect Agent' from the menu on the left side.

   1. 

5. From the Protect Agent dashboard, select the ‘Install’ tab.

   1. 

6. Click the Windows 64-bit download button to begin the download.

Downloading the Agent - PowerShell

In certain scenarios, it may be preferable to download the HPA via PowerShell. The instructions below guide you through that process.

Administrator privileges are required to install via PowerShell

1. Verify the latest version of the Windows 64-bit Agent.

   1. Navigate to the HYAS Protect UI, Settings>Protect Agent> Install. The download buttons confirm the latest Agent version number.

Invoke-WebRequest https://protect-updates.hyas.com/windows/msi/HYAS-Protect-latest.msi -OutFile "$env:USERPROFILE\Downloads\HYAS-Protect-latest.msi"

3. The HPA has now been downloaded to your local ‘Downloads’ folder.

Installing the Agent - Interactive

Now that you’ve downloaded the Agent, its time to install it. This walks you through how to complete an interactive install. Instructions on a silent install in the next section.

1. Navigate to your downloads folder and double click the HYAS-Protect-latest file.

2. Follow the steps in the Setup Wizard below:

   1. Click “Next”

      

   2. Paste your Install Key here and click, “Next”.

      1. To obtain your Install Key, navigate to the HYAS Protect UI>Settings>Organization Settings> Protect Agent> Install. Copy your Install Key and paste it here.

      2. 

   3. Confirm installation location by selecting “Next”.

      1. 

   4. Click “Install” to begin the installation process

   5. Select “Yes” from the User Account Control popup.

   6. Finally, click on “Finish” and you’re all set! The HPA is now protecting your machine!

      1. 

By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is running or not.

Installing the Agent - Silent

A ‘silent’ installation means that the application is installed or deployed without any input or interaction from the end user. To silently install the HPA, please follow the steps below.

Please make sure to follow ALL of the steps listed below BEFORE attempting to execute this command.

This assumes the Agent has already been downloaded to the machine.

1. Copy the following curl command

   1. POWERSHELL

      $msi_file = "$HOME\Downloads\HYAS-Protect-latest.msi"
      $client_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      $msi_args = "/I `"$msi_file`" CLIENTID=$client_id /quiet /log protect_install.log"
      Start-Process -FilePath msiexec.exe -ArgumentList $msi_args -Wait

2. Replace the client_id, noted above as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your client ID

   1. To obtain your client_id, navigate to the HYAS Protect UI>Settings>Organization Settings> Protect Agent> Install. Copy the ‘Install Key’, this is your client_id

3. Once you’ve changed both variables noted in step 2 run the command.

If the installation does not complete successfully, please make sure you’ve updated the variable in step 2 above.

Deploying the Agent via Microsoft Intune

Deploying the Windows version of the HPA can also be done via Microsoft Intune. Please see our Instructional Guide for more information.

Starting the Agent UI

By default, the Agent’s UI will not launch upon install however, the HPA service is running and protecting your machine in the background.

The HPA UI provides feedback, status updates and other information related to the HPA. If you wish to start the UI to view these, please perform the following steps:

1. To start the HPA UI,

   1. Navigate to the search bar and type HYAS Protect

      1. 

   2. Click on HYAS Protect

      1. 

Checking Agent Status

When checking status, keep in mind that the HPA communicates with the HYAS Protect backend approximately every 5 minutes, so statuses may not appear immediately in the HYAS Protect SaaS UI.

HYAS Protect SaaS UI

Administrators may check the status of all HPA’s from the ‘Manage’ tab in the ‘Protect Agent’ section of the HYAS Protect SaaS UI.

1. Login to HYAS Protect, click on Settings>Organization Settings> Protect Agent> Manage.

   

2. From this view, you can check the ‘Status’ column to get information on the status of all the Agents.

HYAS Protect Agent UI

It is also possible to check the status of the HPA on the local machine itself.

By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is open or not.

1. Ensure the HPA UI is running.

   1. If you do not see the HYAS in the system tray, the HPA UI is not running. This does not mean that HYAS Protect is not protecting the machine. This only means the UI is not running.

      1. 

   2. To start the HPA UI follow the instructions listed above under ‘Starting The Agent UI’

2. With the UI running, click on the HYAS icon in the system tray.

   1. You’ll be presented with the following window:

      

3. Green means everything has passed checks and is working properly. Red signifies that there is an issue with the status and further troubleshooting may be required.

4. Additionally, you may check Services to ensure the HPA is running

Agent Status Definitions

Protection Active

• This shows the overall status of the Agent.

Internet Check

• The HYAS Protect service performs the DNS query directly to the HYAS Protect cloud resolver. If this works, the service can reach the internet and can reach the HYAS Protect cloud backend.

Proxy Check

• The HYAS Protect service performs the DNS query to 127.0.0.1:53. If this works, the service is correctly listening on 127.0.0.1:53, and can reach the internet and the HYAS Protect cloud backend.

OS Check

• The HYAS Protect service asks the OS to perform the DNS query. If this works, the OS is configured to use 127.0.0.1:53 for DNS, the service is correctly listening on 127.0.0.1:53, and can reach the internet and the HYAS Protect cloud backend.

Agent Preferences

The HPA on the local machine includes configurable preferences to provide greater flexibility, visibility, and advanced troubleshooting. To access Preferences, start by navigating to the system tray and click on the HYAS Protect icon.

• Once you click on Preferences, you’ll see the three options below:

• Start UI at login

  • Enabling this will ensure that the GUI is started on machine login.

The HPA will still run in the background - and be protecting your machine - regardless whether the UI is running or not.

• Notifications

  • Turning this on allows the Protect Agent to send you notifications regarding connectivity or errors that may have occurred.

• Debug Mode

  • Toggling this on can be useful if you’re having issues with your Agent. This feature enables additional logs to be collected for Client Admin or HYAS analysis.

Disabling/Enabling the Agent

Disabling

There are a few different options to “Turn off” the Agent. Let’s dive into the differences.

Disabling the UI only

This turns the UI off but allows the HPA to still run in the background.

1. Click on the HYAS Protect icon in the Menu Bar to access the settings. You’ll see the following popup.

   1. 

   2. Clicking “Quit” here will turn off the HYAS Protect UI.

The HPA will still run in the background - and be protecting your machine - regardless whether the UI is running or not.

Re-enabling the UI only

• If the HYAS icon is missing from the Menu Bar, it means the UI isn’t running.

  • To start the UI, see instructions above titled, ‘Starting the Agent UI’

Disabling Protection Locally

If you wish to disable the HPA completely, you must stop the service itself.

This will completely stop HYAS Protect from running and it will no longer be protecting your machine.

1. Click on the HYAS icon in the Menu Bar.

2. Select, ‘Disable Protection’

   1. This will disable the HPA completely for a period of 5 minutes.

If you are unable to select ‘Disable Protection’, your Administrator must toggle the feature on via the HYAS Agent Central Management Console. Instructions for Admins on completing that here.

Re-enabling Protection Locally

The HPA will automatically restart after 5 minutes. However, if you wish to restart the HPA sooner perform the following:

1. Navigate to the HYAS Logo in the Menu Bar, click on it and select ‘Enable Protection’

2. This will re-enable the HPA to begin protecting your device again.

Disabling Protection via the HPA Central Management Console

HYAS Protect Admin privleges are required to manage agents in the Central Agent Management Console.

1. Navigate to the ‘Manage’ tab of HPA Central Agent Management Console.

2. Select the Agent(s) you wish to disable by selecting the check box next to the Agent(s) and selecting the ‘Action’ button at the top of the screen or by selecting the Actions icon at the right of the page.

3. Then select ‘Disable Agent'

   

This will disable the Agent indefinitely. The HPA must be manually re-enabled before it can resume protecting the selected devices.

Confirming the Agent’s Running State

By default, the Agent runs in the background and automatically protects your machine upon installation. However, if you’d like to confirm that it’s running, you can do so by following one of the procedures below:

By default, the Agent’s UI will not launch, but rest assured, the service will still be running and actively protecting your machine whether the UI is running or not.

If the UI is NOT running (default state)

1. Start the Agent’s UI by following the instructions above under ‘Starting the Agent UI’.

If the UI is running

1. Navigate to the system tray at the bottom of the screen and you should see:

   

   1. The H with the solid dot signifies that the HPA, (both service and UI is up and running).

Updating the Agent

Like all software, regular updates are crucial for fixing bugs, adding new features, and improving client experience and overall security. The update method for the HPA may differ depending on the version, so please refer to the instructions below for details specific to your version.

Regardless of the update method, HYAS STRONGLY recommends using a phased rollout approach. This involves updating a few machines at a time, testing them, and then proceeding with additional updates. This standard practice for software updates helps ensure easier troubleshooting and minimizes the risk of widespread issues.

Agent v2.2.7 and Newer

If you machine(s) are currently on HPA v2.2.7 or newer, you may update to newer versions (2.2.8+), directly from the HYAS Protect SaaS UI.

1. Navigate to HYAS Protect, click on Settings>Organization Settings> Protect Agent> Manage.

2. Select the machine(s) you which to update (ensuring they are running v2.2.7 or newer)

3. Click on ‘Action’

   

4. Then select ‘Update Agent (v2.2.7)’

   

5. Allow up to 15 minutes for the updates to complete.

Agent v2.2.6 and Older

If you have HPA v2.2.6 or older you will not have in-place updating capabilities until you’ve updated to v2.2.7+. This means, you need to manually update your agents.

However, if you are updating to v2.2.5 or newer, it will automatically look for older versions of the HPA dating back to at least 2.1.1 and automatically uninstall the older version as part of the update process.

In all other cases, please manually uninstall the older HPA per the instructions below. For installation, follow the instructions listed above for downloading and installing the HPA.

Uninstalling the Agent

v2.2.6 and Newer

If your machines are running v2.2.6 or later, the easiest way to uninstall the HPA is through the ‘Manage’ tab in the HYAS Protect SaaS UI

1. Navigate to HYAS Protect>Settings>Organization Settings>Protect Agent>Manage

2. From the ‘Manage’ tab, select the machines you wish to uninstall the Agent from, click on ‘Action’ and select ‘Uninstall (v2.2.6+)’

3. After approximately 5 minutes, the HPA will be uninstalled from the desired machines.

v2.2.5 and Older

Older versions of the HPA require a different procedure, although this method will also work on newer versions as well.

1. Navigate to the search bar and type “Add or Remove Programs”

2. Click on “Add or Remove programs”.

   1. This will take you to the “Apps & features” section.

3. Search for HYAS Protect in the list.

4. Click on HYAS Protect and select Uninstall.

5. Follow the prompts to fully uninstall HYAS Protect.

VPN Compatibility

HYAS understands that some organizations utilize VPN's for enhanced security and privacy. Therefore, HYAS has conducted extensive compatibility testing with many of the most popular VPN’s in use today. However, it's important to recognize that not all VPN's have been tested with the HPA. As such, organizations using VPN's not explicitly tested by HYAS should exercise caution and consider conducting their own compatibility assessments to ensure seamless integration and optimal performance.

It should be noted that in some cases, the VPN must be disabled in order to give preference to the HPA to resolve DNS queries. Once a VPN is disabled, the HPA will automatically take over DNS resolution capabilities.

Troubleshoot

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:

  • Navigate to the UI

    • Then go to Settings>Protect Agent

  • 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.

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

  • Navigate back to your Windows machine.

    • Right-click on the HYAS Protect icon in the Notification Tray and you’ll see the version number at the bottom of the window.

      

• If your 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 “C:\protect\logs\dnsproxy.log”

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 one of the above recommended methods and stop the service via the UI or PowerShell.

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 one of standard procedures 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 connect to 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

Unable to Connect to the Internet

Issue

Unable to connect to known network after installing the HPA.

Solution

There can be a number of reasons why a device cannot connect to the internet. First, check your local machine settings to ensure your Wi-Fi is turned on. If you’re using an Ethernet cable, verify that it is securely connected to both your computer and the router. Verify all hardware is turned on and working properly.

Restart the machine. Most issues can be resolved by restarting the machine running the HPA.

If you’ve completed all standard diagnostic procedures and still suspect an issue with the HPA, please request the Protect Agent Advanced Debugging Guide from your HYAS representative for further troubleshooting.

Also, if you need immediate access to the internet, disable the HPA via the web UI.

Unable to Connect to the Internet After Uninstalling the HPA

Issue

Unable to connect to to the Internet after uninstalling the HPA

Solution

In some cases on Windows machines running older versions of the HPA, the uninstallation process fails to revert known networks to their DHCP settings, rendering connections to said networks impossible. A “known network” refers to a network previously connected to by the machine while the agent was active. “Forgetting” the network does not rectify this issue. 

Workaround

• The end user will need to connect to a new network the agent has not encountered. This will enable an IT administrator to remote in and reset DHCP for the network.

• To avoid this problem, disable the HYAS Protect service. The following command can be used to identify if the network reset was successful ‘ipconfig /all | findstr DNS’. If the DNS settings show “::1” or “127.0.0.1” then it was not successful. If the network has not been successfully reset, re-enabling the service is necessary. It’s important to note that uninstalling the agent might leave the user without network connectivity.

Additional Troubleshooting Scripts for PowerShell

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

View Local Log

Get-Content -Path "C:\protect\logs\dnsproxy.log" -Wait

Uninstall

Uninstall-package -Name "HYAS Protect"

Check running state

Get-Process | Where-Object { $_.Path -like "*dnsproxy*" }
Get-Service | Where-Object { $_.Name -like "*hyas*" }
Get-Process | Where-Object { $_.Path -like "*hyas protect.exe*" }

Stop Service

    Stop-Service "HYAS Protect"

Start Service

    Start-Service "HYAS Protect"