Configuring an agent for on-premises data sources

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

An agent is a service that runs on a local machine and connects an internal service to SquaredUp. The agent listens to the queue from SquaredUp and picks up tasks, for example running scripts to provide data that SquaredUp has asked for.

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

Troubleshooting an agent

Prerequisites

• The agent needs to run on a Windows machine that has access to the entry point for the on-premises 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

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

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

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

   • SCOM data source

   • Custom PowerShell data source

   • VMware data source

   • Solarwinds data source

   For example:

   "name": "results.displayName" would become "name": "displayName"

   and

   "rowPath": ["results"] would become "rowPath": []

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.

Troubleshooting an agent

An agent's status is shown in SquaredUpSettings > 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/