Configuring an agent (Windows platforms)

This article walks you through the steps for downloading, deploying, configuring and upgrading an agent for on-prem data sources on a Windows platform.

Relay Agents allow you to securely connect on-prem data sources that run on your internal network to SquaredUp. For information on Relay see Relay Agent.

Prerequisites

Deploying multiple agents

How to deploy an agent

How to check the version of an agent currently installed

How to upgrade an agent

How to remove an agent

Add agents to security exclusions

Troubleshooting an agent

Prerequisites

• The agent needs to run on a Windows machine that has access to the entry point for the on-prem data source.
• Make sure the agent is able to make outbound connections on port 443 to SquaredUp (api.squaredup.com / eu.api.squaredup.com, depending on your region), *.amazonaws.com and Microsoft Azure Relay (*.servicebus.windows.net) - this may include firewall rules and proxy server allow lists.
• If a Proxy is required, set a system environment variable named ALL_PROXY with the location of the proxy server, as modern .Net applications do not use the proxy as shown in netsh.

  The proxy server may be a hostname or IP address (optionally followed by a colon and port number) or it may be a http URL (optionally including a username and password for proxy authentication). A proxy URL must be started with http, not https, and cannot include any text after the hostname, IP, or port. If the agent is running as a service, you will need to restart it, and may need to restart the server itself in some cases in order to apply the environment variable.

• For information about Relay Agent versions see Release Notes - Relay Agent

Deploying multiple agents

Typically, you should be able to service all of your needs with a single agent, deployed into your internal network. However, should you have many isolated networks (either physical or virtual) that you wish to gather data from, you may need to deploy more than one agent.

The agent will typically be deployed as its own shared service into a network communicating with multiple data sources, but if you have applications in isolated virtual networks (such as a microservices app with only open ports for front end access), you may find it convenient to add an agent into the existing service definition and manage them together as a single unit.

See the Relay Agents documentation to learn more about managing multiple agents.

How to deploy an agent

1. Create a unique API key for your agent and add the agent to an agent group in SquaredUp.
   You create an API key by creating an agent in SquaredUp:
   
   1. Go to Settings > Relay and add an Agent.
   2. Give the new agent a name and a description that helps you identify where the agent is installed. For example:
      Name: server1.domain.local
      Description: Test server in production domain
   3. Choose the Agent Group for this agent:
      1. If you already have agent groups, assign it to an existing group and click create.
      2. If you don't have any agent groups yet or want to assign the new agent to a new group, leave the Agent Groups field empty and click create. Then create the agent group by clicking on Add Agent Group and select the new agent in the Agents field for the new group.
   4. After you created the agent, the API key for this agent will be shown to you. Copy the key and store it until you inserted the key into the configuration of the agent you want to deploy on your machine.

      The API key will only be displayed to you once. If you lose this API key, you need to generate a new one (by creating a new agent) and any references to the old API key in the configuration of the agent you deployed on your machine will need to be updated.

   5. The agent status will show as gray until the next stage of configuring the service is completed successfully.
2. Deploy the agent on a machine that has access to the service the data source connects to.
   1. Download the latest release of the SquaredUp agent zip file, by clicking the download icon under Options next to the agent you have just added.
      Prerequisites for agents

      • The agent needs to run on a Windows machine that has access to the entry point for the on-prem data source.
      • Make sure the agent is able to make outbound connections on port 443 to SquaredUp (api.squaredup.com / eu.api.squaredup.com, depending on your region), *.amazonaws.com and Microsoft Azure Relay (*.servicebus.windows.net) - this may include firewall rules and proxy server allow lists.
      • If a Proxy is required, set a system environment variable named ALL_PROXY with the location of the proxy server, as modern .Net applications do not use the proxy as shown in netsh.

        The proxy server may be a hostname or IP address (optionally followed by a colon and port number) or it may be a http URL (optionally including a username and password for proxy authentication). A proxy URL must be started with http, not https, and cannot include any text after the hostname, IP, or port. If the agent is running as a service, you will need to restart it, and may need to restart the server itself in some cases in order to apply the environment variable.

      • For information about Relay Agent versions see Release Notes - Relay Agent

   2. On a Windows machine, with access to the entry point your data source needs to use, extract the downloaded zip file.
   3. In the folder of the extracted zip file, open PowerShell as an administrator and run the following command:
      Copy

      ./Install-SQUPAgent.ps1 -ApiKey "key" -AsService -ServiceSuffix "name" -ServiceAccount domain\username

      
      Parameters to replace:

      -ApiKey "key"	Mandatory	Replace key with the API key you created for the agent in SquaredUp
      -AsService	Recommended	Run the agent as a service on the machine
      -ServiceSuffix "name"	Optional	To change the default service name of squpagent replace name with your new service name.
      -ServiceAccount domain\username	Optional	To run the agent as a domain service account (for example, for the SCOM data source), provide the username as domain\username and it will prompt for the password when it sets up the service
      -InstallPath	Optional	Specify a folder location for where the agent will be installed. If this is not specified then the agent will be installed in the folder where the zip file is extracted.

      Consider restricting access to the folder where the agent is installed to prevent anyone from updating or viewing the configuration files.

   Running the agent as a domain service account

   By default, the SquaredUp agent service uses the local system identity, but this can be changed to a domain service account if required, for example for the SCOM data source.

   • Configure a domain service account using the installation script, for example:
     ./Install-SQUPAgent.ps1 -ApiKey "key" -AsService -ServiceAccount domain\username
     where key is the API key, and domain\username is the domain service account
   • Alternatively, in Services > SquaredUp Cloud Agent > Properties select the account on the Log On tab.
   • Use a dedicated user account for the agent's service identity. Create a special service account for this domain service account, do not use an existing user account.
   • The account (typically a service account) needs to have the log on as a service permission.

   1. Adjust any permissions for the service and start the service.
      How to start the agent service

      You can start the agent service from Services > SquaredUp Cloud Agent, or using PowerShell using either:

      Start-Service -Name <ServiceName>

      Where <ServiceName> should be replaced with the service name shown in brackets in the upgrade script output (or Properties of the service).

      For example:

      Start-Service -Name squpagent

      or

      Start-Service -DisplayName <DisplayName>

      Where <DisplayName> should be replaced with the service name shown before the brackets in the upgrade script output (or Properties of the service).

      How to find the agent folder location or Service name in Properties

      Look at the Properties of the SquaredUp Cloud Agent service:

      1. On the server running the agent, open Services
      2. Scroll down to the SquaredUp Cloud Agent in the list
      3. Right-click on the SquaredUp Cloud Agent service and then Properties
      4. Here you can see the Service name, Display name and Path to the agent folder.
      5. You can also start or stop the service from here.

   2. Check the agent status in SquaredUp Settings > Relay

How to check the version of an agent currently installed

You can find the agent version number in the Properties of the SquaredUpCloud.WinAgent.exe executable or in the log files:

1. On the server running the agent, open the folder where the agent is installed.
   How to find the agent folder location or Service name in Properties

   Look at the Properties of the SquaredUp Cloud Agent service:

   1. On the server running the agent, open Services
   2. Scroll down to the SquaredUp Cloud Agent in the list
   3. Right-click on the SquaredUp Cloud Agent service and then Properties
   4. Here you can see the Service name, Display name and Path to the agent folder.
   5. You can also start or stop the service from here.

2. Right-click on the SquaredUpCloud.WinAgent.exe executable then Properties then Details.
3. File Version shows the version of the agent that is installed.
4. Alternatively, you can see the agent version at the top of any of the log files. Log files are located in the agent\transient\logs folder.

See Release Notes - Relay Agent

How to upgrade an agent

The upgrade script needs to be run on the Windows machine running the agent.

1. Go to Settings > Relay and download the latest release of the SquaredUp agent zip file from the download icon under Options for your agent.
2. On the Windows machine running the agent, extract the downloaded zip file at the same level as (next to) the agent folder.
   How to find the agent folder location or Service name in Properties

   Look at the Properties of the SquaredUp Cloud Agent service:

   1. On the server running the agent, open Services
   2. Scroll down to the SquaredUp Cloud Agent in the list
   3. Right-click on the SquaredUp Cloud Agent service and then Properties
   4. Here you can see the Service name, Display name and Path to the agent folder.
   5. You can also start or stop the service from here.

3. Open PowerShell as an administrator and run the following command:
   ./Install-SQUPAgent.ps1 -upgrade
   The upgrade script will stop the agent service.
   Make a note of the ServiceName for the next step. The upgrade script output shows the DisplayName followed by the ServiceName in brackets:
   VERBOSE: Performing the operation "Stop-Service" on target "SquaredUp Cloud Agent (squpagent)".
4. Start the agent service.
   How to start the agent service

   You can start the agent service from Services > SquaredUp Cloud Agent, or using PowerShell using either:

   Start-Service -Name <ServiceName>

   Where <ServiceName> should be replaced with the service name shown in brackets in the upgrade script output (or Properties of the service).

   For example:

   Start-Service -Name squpagent

   or

   Start-Service -DisplayName <DisplayName>

   Where <DisplayName> should be replaced with the service name shown before the brackets in the upgrade script output (or Properties of the service).

   How to find the agent folder location or Service name in Properties

   Look at the Properties of the SquaredUp Cloud Agent service:

   1. On the server running the agent, open Services
   2. Scroll down to the SquaredUp Cloud Agent in the list
   3. Right-click on the SquaredUp Cloud Agent service and then Properties
   4. Here you can see the Service name, Display name and Path to the agent folder.
   5. You can also start or stop the service from here.

5. Check that configured data sources are available in the agent\transient\plugins folder. The required connectors should be available in the agent\transient\connectors folder shortly after running the upgrade.
6. Check that dashboards using built-in data streams work as expected.
7. If you have created any custom data streams (either manually or via configurable data streams) that depend upon the following data sources, you will need to update the rowpath and column name properties in each data stream to remove the “results." suffix:
   For example:
   "name": "results.displayName" would become "name": "displayName"
   and
   "rowPath": ["results"] would become "rowPath": []
   • SCOM data source
   • Custom PowerShell data source
   • VMware data source
   • Solarwinds data source
8. Once you have checked everything is working, remove the backup folder.

   The backup folder is created in case you need to roll-back: You can stop the service, delete or rename the existing agent folder, rename the backup folder to agent, and then restart the service.

How to remove an agent

1. On the server running the agent, locate the SquaredUp agent service you wish to remove.
   Services > SquaredUp Cloud Agent.
2. Right-click Properties and make a note of the Service name and the Path to executable.

   

   If the agent was configured without a suffix (i.e. a single instance of the agent) then the service name will be squpagent. If a suffix was specified when the agent was configured, a version of the suffix (with spaces and other special characters swapped for "-") will be appended to the name.

3. Open PowerShell as an administrator and run the following command:
   Copy

   sc.exe delete squpagent

   
   Where squpagent is replaced with the service name if it is not simply squpagent.
   How to find the agent folder location or Service name in Properties

   Look at the Properties of the SquaredUp Cloud Agent service:

   1. On the server running the agent, open Services
   2. Scroll down to the SquaredUp Cloud Agent in the list
   3. Right-click on the SquaredUp Cloud Agent service and then Properties
   4. Here you can see the Service name, Display name and Path to the agent folder.
   5. You can also start or stop the service from here.

   This will remove the service from Windows.
4. Finally, delete the agent folder, as referenced in the Path to executable above.

Add agents to security exclusions

To ensure that the Relay agent functions correctly, it is strongly recommended that you add the process to the list of exclusions for each of your virus, AppLocker and heuristic scanners.

For configuring Windows security exclusions, see Add an exclusion to Windows Security and AppLocker.

For any other security applications refer to the corresponding documentation.

Troubleshooting an agent

An agent's status is shown in SquaredUp Settings > Relay as a green tick, amber exclamation mark, red cross or gray question mark. Hovering over the status will show information about the last connection.

If the agent status is not green:

1. Check that the agent service is running (in Services on the server running the agent).
2. Check that the API key is correct. In SquaredUp you can see the last 4 digits of the API key in Settings > Relay and compare this with what's in the appsettings.json file in the agent folder /agent/transient/logs. If necessary, you can edit the agent and click Regenerate API Key to get a new key, then copy that into the appsettings.json file.
   
   How to find the agent folder location or Service name in Properties

   Look at the Properties of the SquaredUp Cloud Agent service:

   1. On the server running the agent, open Services
   2. Scroll down to the SquaredUp Cloud Agent in the list
   3. Right-click on the SquaredUp Cloud Agent service and then Properties
   4. Here you can see the Service name, Display name and Path to the agent folder.
   5. You can also start or stop the service from here.

3. Check the agent logs for any connectivity errors. Support may ask you to change the LogLevel from Information to Debug in the appsettings.json file.
4. Check SquaredUp for any reported outages: https://squaredup.statuspage.io/