Configuring an agent (Linux platforms)

This article walks you through the steps for downloading, deploying, configuring and upgrading an agent for on-prem data sources on a Linux platform. This deployment method is containerized, which allows you to deploy across multiple platform types and also provide a smoother experience when deploying to 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

Deploying from a Docker image

Starting an agent

Viewing agent logs

Prerequisites

API key

Prior to starting an agent, you must log into your SquaredUp tenant, create a Relay Agent and assigned it to one or more agent groups. Creating an agent registers it for use with SquaredUp and creates a unique API key that identifies that agent.

The API key can be injected into the container using a number of mechanisms. Depending on your organization's policies and practices, you may have a variety of different tools at your disposal to store the key and ensure that it is securely provided to the container.

The examples in Starting an agent show how to provide the key using both environment variables and volume mounts for simplicity, but be aware that users who have access to the container host will be able expose the key using these methods. Consult your own organizational best practices to ensure that the API key is not compromised.

How to create an API key

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.

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.

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.

Deploying from a Docker image

The Relay Agent can be deployed from a Docker image by using the following docker pull command- docker pull squaredup/relay-agent.

Deploying a Relay Agent in a Linux container removes the need for a Windows VM and gives Linux users a native platform they are comfortable with. If you are deploying into a service like Kubernetes (which typically only exposes the front end to the outside world) you can put the agent into the cluster without having to open ports and compromise the isolated environment your app is running in.

Additionally, a Linux container can be run in Azure / AWS for cheaper than a VM and can be much easier to manage and maintain.

Supported tags

The image repository provides both immutable tags, and rolling tags for each segment of a semantic version number, along with latestand -rc tags.

We suggest that, regardless of tag, you make use of the latest version of the agent available but the choice of which tag should be based on your practices and application needs. For many users, especially those deploying a shared agent as its own service, the Major tag is suitable, allowing you to receive updates during container provisioning operations, whilst isolating them from any breaking changes. The SquaredUp UI will also display an icon next to any agent that is running an outdated version, should you wish to use an immutable tag and still be notified of updates.

Immutable tags:

• Major.Minor.Patch.Build

Rolling tags

• Major.Minor.Patch, Major.Minor, Major
• Major.Minor.Patch-rc (release candidate)
• latest

Update appsettings.json (EU region)

If you are connecting to the EU region of SquaredUp (eu.app.squaredup.com), then after you deploy the Relay Agent you must update your /app/appsettings.json file with the region-correct Url and DownloadUrl values.

{
    "RelaySettings": {
        "ApiKeys": [
            {
                "Enabled": true,
                "ApiKey": "xxxxxxxxxxxxxxxx",
                "Description": "My Agent",
                "Url": "https://eu.api.squaredup.com/api/hybridconnection",
                "DownloadUrl": "https://eu.api.squaredup.com/api/agentdownloads"
            }
        ]
    },
    "LogLevel": "Information"
}

Starting an agent

Specify API key via environment variable

Use one of the the following commands to start an instance of the Relay Agent, depending on your region:

• US region:
  Copy

  docker run -d --name SquaredUp-Agent -e RelaySettings:ApiKeys:0:ApiKey=XXXXXXXXXXXXX squaredup/relay-agent:tag

• EU region:
  Copy

  docker run -d --name SquaredUp-Agent -e RelaySettings:ApiKeys:0:ApiKey=XXXXXXXXXXXXX -e RelaySettings:ApiKeys:0:Url=https://eu.api.squaredup.com/api/hybridconnection -e RelaySettings:ApiKeys:0:DownloadUrl=https://eu.api.squaredup.com/api/agentdownloads squaredup/relay-agent:tag

Where SquaredUp-Agent is the name you wish to assign the container, XXXXXXXXXXX is your API key, and tag is the tag specifying the agent version you want. See the tags tab for relevant tags.

Configuration file via volume mount

If you wish to use a configuration file, you can mount the following file into your container at /app/appsettings.json:

{
    "RelaySettings": {
        "ApiKeys": [
            {
                "Description": "Friendly name to be used in logs instead of last 4 key digits",
                "ApiKey": "XXXXXXXXXXXXXXXXXX"
            }
        ]
    },
    "LogLevel": "Information"
}

The description attribute is optional, and simply provide a friendly identifier in log entries instead of using the last four digits of the API key. The following command mounts the file from the working directory into correct location in the container:

docker run -d -v appsettings.json:/app/appsettings.json squaredup/relay-agent

Using secrets with Docker Compose

You can use the secrets functionality of Docker Compose to inject the API key in a more secure fashion. In this example compose.yml the agent is started using the same config JSON in Configuration file via volume mount , injected from the local file appsettings.json:

name: squaredup

services:
  agent:
    hostname: squaredup-containerhost # sets the hostname value as it appears in the Cloud
    image: squaredup/relay-agent:tag
    restart: on-failure
    secrets:
      - source: squp_config
        target: /app/appsettings.json

secrets:
  squp_config:
    file: ./appsettings.json

The name and hostname attributes are optional, and can be specified to make it easier to track the containers and agent at a later date. To create and start the agent, you can simply run:

docker compose up -d

Using secrets with Docker Swarm

When running a Swarm, secrets are managed by your cluster and will be securely replicated to each node within it, as they are encrypted during transit and storage, and are held in memory so they won't be found on individual nodes or container filesystems. In addition, secrets are only sent to swarm managers and nodes that are running containers that require them.

To create a secret from a local file named appsettings.json that contains the agent config, run:

docker secret create squp_agent_config appsettings.json

The secret name squp_agent_config is user configurable, but you will need to remember it for the next step.

Finally, start the container and grant it access to the secret by running:

docker service create --name squp_agent --secret source=squp_agent_config,target=/app/appsettings.json squaredup/relay-agent:tag

Using secrets with Docker Swarm and Compose files

You can reference existing Swarm secrets in services to be managed by Docker Compose. First you must create your secret as above using docker secret create.

Next, you can reference it in your Compose file by setting external: true on the global secret definition. This tells Compose not to attempt to create a new secret, and instead to take the existing value from the swarm.

name: squaredup

services:
  agent:
    hostname: squaredup-containerhost # sets the hostname value as it appears in the Cloud
    image: squaredup/relay-agent:tag
    restart: on-failure
    secrets:
      - source: squp_config
        target: /app/appsettings.json

secrets:
  squp_config:
    external: true

Viewing agent logs

When running in a container, the agent will print all log entries to StdOut. These are then available via docker logs containername when running detached, or in whatever log providers you may have configured.

When specifying the agent configuration through appsettings.json you also have the option to set the log level verbosity to Warning or Error if you wish to decrease the amount of logs stored and removal operational messages logged at the Information level (the default).

For troubleshooting purposes, SquaredUp support may ask you to set the LogLevel to Debug, but this should only be performed temporarily as this is an extremely verbose mode and can generate a large volume of log data.

Was this article helpful?