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.

For information on deploying to a Linux platform, see Deploying a Relay Agent in a Linux container .

An on-prem data source uses a relay agent to connect SquaredUp to a data source running on your internal network.

A relay agent is installed on a server on your internal network, and has access to your data source.

Using a relay agent means that you don't need to open your firewall to allow access.

For more information see Relay Agents.

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.

Agents should never share API keys, as this will result in data requests being sent to the wrong network.

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.
    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: 
      ./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.

    1. Adjust any permissions for the service and start the service.
    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:

  1. On the server running the agent, open the folder where the agent is installed.
  2. Right-click on the SquaredUpCloud.WinAgent.exe executable (in the Agent folder) 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 the agent log file after the agent is started up/restarted. Log files are located in the agent\transient\logs folder.

See How to upgrade an agent

See Release Notes - Relay Agent

How to check the identity (Log On account) of a relay agent

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
    Here you can see the Service name, Display name and Path to the agent folder.
  4. The Log On tab shows you which account the service is logging on with. (Needed for the SCOM and CSV plugins)
  5. You can also start or stop the service from the General tab.

How to change the identity of a relay agent

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

How to upgrade an agent

See How to check the version of 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 All from the downloaded zip file (SquaredUpCloudAgent....zip) to the same level as (next to) the Agent folder, so that the contained zip (SQUPAgent...zip) is at the same level as the Agent folder.
  3. Open PowerShell as an administrator and run the following command:
    ./Install-SQUPAgent.ps1 -upgrade

    If the upgrade gives an error check that you don't have any of the files, such as log files, open.


    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)".

    You can also put the zip file and script wherever you want and use the optional parameter -InstallPath to tell the script exactly where the agent is installed. This path should point to the folder that contains the existing installed Agent folder.

    For example, if your path to the SquaredUpCloud.WinAgent.exe was C:\SquaredUp\Agent\SquaredUpCloud.WinAgent.exe you'd run the following:
    Install-SqupAgent.ps1 -upgrade -InstallPath C:\SquaredUp\

  4. Start the agent service.
  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: 
    sc.exe delete squpagent

    Where squpagent is replaced with the service name if it is not simply squpagent.
    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.
  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/

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket