Common Tetra Agent Upgrade and Installation Information

The following installation and upgrade actions are common to all Tetra Agents:

Upgrade Tetra Agent Software

To upgrade a Tetra Agent, do the following:

See the following sections to learn how to do each of these things.

Review the Release Notes for the Upgraded Version

Review the release notes for the upgraded Agent version. To view Agent release notes, see Tetra Agent Release Notes.

Prepare the Tetra Agent

To prepare to upgrade a Tetra Agent, do the following:

  1. Open the Tetra Agent's Management Console.
  2. Verify that the Tetra Agent isn't processing data.
  3. Verify that the Management Console for the Tetra Agent isn't running for any user who's logged in.
  4. Stop the Tetra Agent.
  5. Note the configuration settings. You will need this information when you verify the upgrade.
  6. Close the Tetra Agent's Management Console.
  7. Copy the SQLite Database's applicationdb.sqlite file and store the file in a safe place. The file location differs by Tetra Agent:
    • Tetra Chromeleon Agent: <Directory where you installed the agent>\Bin\Database
    • Tetra Empower Agent: <Directory where you installed the agent>\db
    • Tetra File-Log Agent: <Directory where you installed the agent>\Bin\Database
    • Tetra LabX Agent: <Directory where you installed the agent>\Bin\Database
    • Tetra UNICORN Agent: <Directory where you installed the agent>\Bin\Database


Local SQLite Database

Additional runtime states (for example, files pending upload) are stored in a local SQLite database. These files store internal details for the Agent. Don't manually change these files.


Note about Chromeleon Upgrades

For Tetra Chromeleon Agent v2.0.0 and earlier, before you stop the Agent for an upgrade, make sure that you check that the process TetraScience.Agent.Chromeleon.Runner isn't running. To check the process status, open Windows Task Manager. If the process is running, select the process and choose End Task. Then, complete the upgrade.

Perform the Upgrade

To upgrade a Tetra Agent, use the new version of the installation package that you got from your customer success manager (CSM).



When you upgrade an Agent, make sure that you select the Upgrade option instead of the Install option. The Upgrade option upgrades the Tetra Agent that's in-place, rather than replacing, which retains its existing configuration settings and state, but deletes the local copies of the log files.



Log files are backed up in Amazon CloudWatch.

Verify the Upgrade

After you've upgraded the Agent, verify the upgrade by doing the following:

  1. Open the Agent Management Console and verify that the new version displays in the Management Console's title bar.
  2. Verify that the configuration settings are the same as they were before the upgrade.

Upgrade Tetra Agent Hardware

To upgrade the Agent hardware, do the following:

  1. Carefully review the prerequisites and installation instructions for the Agent that you're using. Make sure that the new hardware meets that Agent's hardware requirements.
  1. Follow the instructions in Prepare the Tetra Agent.
  2. Install the Tetra Agent on the new hardware instance by following the Agent's installation instructions.
  3. Replace the SQLite database on the new hardware with the SQLite database that was on the previous hardware.
  4. Follow the instructions in Verify the Upgrade.


Configuration Notes

You can deactivate an Agent if you notice incorrect behavior. When you deactivate an Agent, it can't communicate with the TDP until you reactivate it.

If you configure an Agent for S3 Direct Upload, then the temporary AWS credentials are valid and used until the expiration time (set to less than an hour) is reached. After the Agent reaches the expiration time, the Agent can't retrieve new temporary AWS credentials.

Install Tetra Agent Software

You install each Tetra Agent using a Microsoft Installer (.MSI) package. To get a link to the .MSI package, contact your CSM. Once you have the link, you can download the Tetra Agent to a machine and double-click the Tetra Agent installation file to start the installation wizard. Once installed, you can use the application's user interface to configure and monitor the Agent. Configuration options and parameters are specific to each Agent.

For information about how to install and configure a specific Agent, see the following:

Restrict Access to Agent Installation

To restrict access to the local Agent Management Console, you can edit the Agent’s installation folder’s permissions to grant least privilege access. For more information, see Access Control Overview - Windows Security in the Microsoft Documentation.



Administrator and service user permissions are required for each Agent’s installation folder. You can grant other users access as needed.

Agent User Types

There are three types of Agent users:

  • Administrators: To register the Agent as a Windows Service, Agents must be installed and initially configured by a user with local administrator privileges.
  • Service users: A user role created specifically for running the Agent as a Windows Service. This role should have limited access to the necessary resources (for example, file paths) and access to the Agent’s installation folder.
  • System users: Individuals who use the system locally. These users might not be aware of the Agent, because it’s running as a service in the background.