Configure Legacy Agents from TCP to HTTP in Aternity v9

Aternity v9 requires that all Aternity Agents on devices communicate with it using HTTP or HTTPS. To continue using legacy Agents (v7.1.x or 8.x) after upgrading to Aternity v9, you must reconfigure those Agents to communicate via HTTP or HTTPS (not TCP).


This procedure enables you to continue using legacy Agents (v7.1.x or 8.x) with Aternity v9. You can start to upgrade your devices at any time to Agent 9.x.

To reconfigure all Agents to use HTTP(S), first test the HTTP configuration on several selected devices, to ensure proper connection. Then upgrade the servers to Aternity v9, and finally, after the server upgrades, you can automatically move all Agents to HTTP(S) all in a SINGLE operation, when they reconnect to the Aternity server.

Before you begin

  • You must already have Aternity v7.x or 8.x. Start this procedure before your upgrade to Aternity v9.x.

  • (With HTTP connections) If you deploy more than one dedicated Aternity Aggregation Server, you must deploy a third party load balancer (LB). Then configure the Aternity Agent of all devices to point to the LB's virtual IP address. Configure the LB with persistent (sticky) sessions to ensure the Agent maintains its connection with the same server. In the past it used a built-in load balancer.

    Use a third party load balancer when you have more than one Aggregation Server

    To assess the number of Aggregation Servers required in your deployment, see the sizing guidelines.

  • If Aternity v7.x or 8.x communicated ONLY in TCP, you must adjust your deployment topology (firewalls, ports, proxies and so on) to allow HTTP(S) communication between your monitored devices and the Aggregation Server or load balancer.


    Every Aggregation Server can communicate in both TCP and HTTP(S). You do NOT need to change any settings to enable HTTP(S) on the server itself.

  • To perform the following procedure, you need permission to Edit Advanced Configuration.


  1. Step 1 Test an HTTP(S) connection on some chosen devices by redeploying legacy Agents, and configuring them to use HTTP or HTTPS.

    Alternatively, you can manually change the configuration file of the existing Agents on those devices to use HTTP or HTTPS:

    1. On the device, sign in with local administrator rights.

    2. Backup the file <program_files>\Aternity Information Systems\Agent\Config\agent_config.xml.

    3. Open the agent_config.xml file for editing.

    4. Search for <value>.

    5. Replace everything between <value> and </value> with only a single entry. For Agent 8.x it would be:

       <EPMAddressSet id="1">
          <EPMAddress Hostname="http://IP_or_FQDN_of_LoadBalancer_or_AggServer:Port" />

      Enter http:// for unsecured or https:// for a secured communication. If you do not add the port number, the default for HTTP is 80, and for HTTPS it is 443.

      For Agent 7.1.x, the EPMAddress tag should be:

      <EPMAddress Hostname="IP_or_FQDN_of_LoadBalancer_or_AggServer" Port="port#" Protocol="HTTPAddress" />

      or for HTTPS Protocol="HTTPSAddress".

      You only need one entry because multiple Aggregation Servers are now balanced by a third party load balancer.

    6. Restart the Agent.

      In the Windows Task Manager or Windows Services console, restart only the A180WD service.

  2. Step 2 Open a browser and log in to Aternity.
  3. Step 3 Select the Gear Icon > Agents to confirm these test devices connect using HTTP protocol.

    It takes 5-10 minutes for this status to update on the screen.

    Search for the hostname of the test device, select it, and confirm that its protocol is now HTTP or HTTPS.

    Confirm the test device reports using HTTP

    If you see this device listed as Disconnected check the following:

    • Confirm you entered the correct address in the agent_config.xml file.

    • Confirm you restarted the Agent.

    • In addition, confirm your routers, firewalls and infrastructure supports devices sending HTTP(S) to the load balancer or Aggregation Server via the designated ports, and check the load balancer routes traffic as expected (with persistent or sticky sessions).

  4. Step 4 Perform the upgrade to Aternity v9.

    After the upgrade, all devices using TCP cannot connect to Aternity until you complete this procedure to update the devivces to use HTTP(S)..

  5. Step 5 Select the Gear Icon > Settings > Advanced Settings > epm > http > server to automatically update all devices to HTTP(S).

    Add the EXACT same address of your Aggregation Server or third party load balancer which you tested on selected devices before the upgrade. Use the following format:


    You must use the EXACT same http address and port number in this format only, otherwise all Agents disconnect permanently from Aternity, and require a manual reconfiguration across the enterprise.

    Automatically reconfigure all connected devices to HTTP(S) by adding the address here

    Enter http:// for unsecured or https:// for a secured communication. If you do not add the port number, the default for HTTP is 80, and for HTTPS it is 443.

  6. Step 6 Wait 10-15 minutes so that actively reporting devices automatically reconnect with HTTP.

    When the legacy Agents try to connect to the server via TCP, the server issues a reconfiguration notice to the Agent to communicate in HTTP.

  7. Step 7 To confirm all devices are Reporting and connect using HTTP, select the Gear Icon > Agents.

    Verify the status of devices by hovering over their icon in the Connection column.

    Select the device to verify it connects with HTTP or HTTPS.

    Confirm the test device reports using HTTP

    If many devices are still Disconnected, access one device with local administrator rights and restart the A180WD service in the Windows Task Manager. If this solves the problem, you can either wait for others to automatically reconnect, or ask users to restart their devices.

  8. Step 8 At any time in the future, you can start upgrading devices to the latest version of Aternity Agent.