This page describes how to upgrade an existing installation of the Machine Agent. The instructions have been tested and certified to work for Machine Agent >= 20.1.  

For a new installation, see Install the Machine Agent.

Perform the Upgrade

  1. Do the following (as needed) before you update the Agent: 
    1. Review the Release Notes for changes that affect your environment.
    2. Back up the <machine_agent_home> directory to a <machine_agent_home_BACKUP> so you can revert to the previous installation, if required. 
    3. If you are upgrading the Controller as well as the Agents: Upgrade the Controller Using the Enterprise Console, and then return to this procedure.
    4. If you have been collecting Log Analytics data by running the Analytics Agent via the Machine Agent: Do the following.
      1. Preserve the old watermark file so that you can copy it to the new <analytics-agent-home>.
              Machine Agent location: <machine-agent-home>/monitors/analytics-agent/conf/watermark
              Analytics Agent location: <analytics-agent-home>/conf/watermark 
      2. Preserve your pre-existing job files so that you can copy them to the new <analytics-agent-home>.
               Machine Agent location:  <machine-agent-home>/monitors/analytics-agent/conf/job
               Analytics Agent location: <analytics-agent-home>/conf/job
  2. Download the installer suitable for your OS environment from the Downloads Portal.
  3. Stop all instances of the Machine Agent that are currently running from the <machine_agent_home> that you want to upgrade. See Start and Stop the Machine Agent
  4. Update your Machine Agent installation:
      • RPM-based Linux installation: 
        Update the existing package. For example:         sudo rpm -U <package>
      • RPM-based installation on a systemd Linux system (such as CentOS 7, Ubuntu, newer Fedora Core systems, newer OpenSUSE systems, and newer SUSE Enterprise Linux systems). 
        If you don't know if your Linux installation is using systemd, do a clean install to avoid issues. Remove the old package and then install the new one. 

      • For all other scenarios: 
        First, delete the <machine_agent_home> for the old Agent. Make sure you retain the <machine_agent_home_BACKUP> you created in Step 1. 
        Then, install the Machine Agent as described Linux Install Using the RPM Package for your specific installation in Install the Machine Agent.

        If you are running the Analytics Agent as an extension to the Machine Agent, failure to clear out the old directory or use a new location may cause your embedded Analytics Agent to fail to start.  

  5. Configure the Agent settings in <machine_agent_home>/conf/controller-info.xml. See Machine Agent Configuration Properties

    The RPM-based Linux installer retains the configuration settings for the previous Agent by default. 

    If you used another installer and want to maintain your previous Agent configuration, copy the <machine_agent_home_BACKUP>/conf/controller-info.xml file to the new installation directory.

  6. Before you start the updated Agent, perform the following steps (as required):
    1. If you are updating on Windows: When you install the new Machine Agent in the existing directory, you may see two "InstallService" and "UninstallService" files. Use the .vbs files (VbScript) and delete the .cmd files (Windows Command Script), which are leftover from your previous version.
    2. If the agent install package includes a new JRE: Update any related custom scripts that use the Machine Agent JRE.
    3. Update all users who have the Account Administrator role for the account and add the appropriate SIM roles (SIM admin and SIM user) to other users in the account, as needed.
  7. Start the Agent, verify the Agent installation, and verify that the Agent is reporting to the Controller as described for your specific installation in Install the Machine Agent.