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

API Key

Prior to deploying an agent, you must first log into your SquaredUp tenant, create a Relay Agent and then assign it to one or more agent groups. This registers the agent for use with SquaredUp and creates a unique API key that identifies it when deployed on your platform.

How to register an agent and create an API key

  1. Navigate to Settings > Relay Agents.
  2. Click Add agent.
  3. Complete the following in the Add agent window:
    1. Name:
      Give the new agent a name that helps you identify where the agent is installed, for example server1.domain.local.
    2. Description:
      Give the agent a description for its purpose. For example, Test server in production domain.
    3. Agent group:
      Choose a group to add the agent to:
      • If you already have an agent group configured, select it from this field.
      • If you already have an agent group configured, or want to assign the new agent to a new group, leave the Agent Groups field empty. Then, after creating the agent, create a new group by clicking Add Agent Group, where you can select the agent in the Agent(s) field.
  4. Click Next. The agent is created and its API key is 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. Click Done to close the window. The agent status displays as gray until the agent is deployed successfully.

Firewalls and proxies

You must ensure the container will be able to make outbound connections on port 443 to:

  • SquaredUp (api.squaredup.com / eu.api.squaredup.com, depending on your region),
  • Amazon S3 instances (*.amazonaws.com)
  • Microsoft Azure Relay (*.servicebus.windows.net)

If a proxy is required for individual containers, set an environment variable named ALL_PROXY with the location of the proxy server:

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

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.

Deploying an agent

  1. Download the latest release of the SquaredUp agent zip file from the Relay Agents page, by clicking Deploy SquaredUp Cloud agent
    next to the agent you created.
  2. Extract the downloaded zip file on a Windows machine with access to the entry point that your data source needs to use.
  3. Open PowerShell as an administrator in the folder of the extracted zip file, then run the following command: 
    ./Install-SQUPAgent.ps1 -ApiKey "key" -AsService -ServiceSuffix "name" -ServiceAccount domain\username

    Parameters to replace:
    Parameter
    Required?
    Description
    -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.

  4. Adjust any permissions for the service and start it. You can then check the agent status in SquaredUp Settings > Relay agents.

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

Starting an agent

You can start the agent service from Services > SquaredUp Cloud Agent, or using PowerShell by running one of the following commands:

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

Managing an agent

Checking an installed agent version

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

Checking the identity (login 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.

Changing the identity of an 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.

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

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

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