How to update Analytics 5.1.x

The procedures on this page update Analytics 5.1.x to 6.0.0. For information about updating earlier releases to 5.1.2, see Upgrading Analytics 5.0.x or Upgrading Analytics 4.x.

Before proceeding, review the release notes.

To perform the update procedures, your Analytics and MariaDB server host must have internet access, and you need permission to download packages from delivery.zenoss.io.

Update the server host operating system

Release 6.0.0 was tested on recent releases of CentOS and RHEL. Before updating the software, Zenoss recommends updating the operating system of the Analytics and MariaDB server host to a tested release. For more information, refer to your operating system documentation.

Perform the procedures on this page in the order in which they appear.

Update MariaDB server

1. Log in to the MariaDB server host as root or as a user with superuser privileges.

2. Stop the Analytics and MariaDB servers.

   service zenoss_analytics stop && systemctl stop mysql
   

3. Remove MariaDB and its dependencies.

   yum remove mariadb-server && yum autoremove
   

4. Create a custom MariaDB 10.6 repository.

   CentOS 7RHEL 8.x

   1. Open the Download MariaDB Server page.

      

   2. Use the form to create a custom repository specification.

      

   3. Determine whether you have a MariaDB repository specification.

      ls /etc/yum.repos.d
      

      If you have one, the file is named MariaDB.repo or mariadb.repo (letter case is ignored).

   4. If necessary, create a file for the repository specification.

      [[ -f /etc/yum.repos.d/MariaDB.repo ]] \
        || touch /etc/yum.repos.d/MariaDB.repo
      

   5. Open the file, copy the specification from the web site, and then paste it into the file.

      Example specification:

      # MariaDB 10.6 CentOS repository list - created 2023-06-29 13:23 UTC
      # https://mariadb.org/download/
      [mariadb]
      name = MariaDB
      # rpm.mariadb.org is a dynamic mirror if your preferred mirror goes offline. 
      # See https://mariadb.org/mirrorbits/ for details.
      # baseurl = https://rpm.mariadb.org/10.6/centos/$releasever/$basearch
      baseurl = https://mirrors.gigenet.com/mariadb/yum/10.6/centos/$releasever/$basearch
      module_hotfixes = 1
      # gpgkey = https://rpm.mariadb.org/RPM-GPG-KEY-MariaDB
      gpgkey = https://mirrors.gigenet.com/mariadb/yum/RPM-GPG-KEY-MariaDB
      gpgcheck = 1
      

   1. Determine whether you have a MariaDB repository specification.

      ls /etc/yum.repos.d
      

      If you have one, the file is named MariaDB.repo or mariadb.repo (letter case is ignored).

   2. If necessary, create a file for the repository specification.

      [[ -f /etc/yum.repos.d/MariaDB.repo ]] \
        || touch /etc/yum.repos.d/MariaDB.repo
      

   3. Open the new file, and then copy the following specification into the file.

      [mariadb]
      name = MariaDB
      baseurl = https://rpm.mariadb.org/10.6/rhel/8/x86_64
      module_hotfixes = 1
      gpgkey = https://rpm.mariadb.org/RPM-GPG-KEY-MariaDB
      gpgcheck = 1
      

5. Update the YUM cache.

   yum clean all && yum makecache fast
   

6. Install MariaDB 10.6.

   yum install mariadb-server
   

   You may encounter errors during the upgrade. If so, try upgrading to release 10.3, then upgrading 10.3 to 10.6.

7. Update systemd.

   systemctl daemon-reload
   

8. Enable start on system boot.

   systemctl enable mariadb
   

Update MariaDB databases

1. Log in to the MariaDB server host as root or as a user with superuser privileges.

2. Remove an outdated configuration setting.

   sed -ie '/innodb_adaptive_hash_index=OFF/ d' /etc/my.cnf
   

3. Start the MariaDB server.

   systemctl start mariadb
   

4. Check the server's status.

   systemctl status mariadb
   

5. Confirm the server is operating normally.

   mysql -u root
   

6. Update databases.

   mysql_upgrade
   

   Typically, the upgrade process takes several minutes to complete.

   You may see the following error:

   ERROR 1932 (42S02) at line 476: Table 'mysql.innodb_index_stats' doesn't exist in engine
   FATAL ERROR: Upgrade failed
   

   To recover, perform this procedure.

Update Analytics

1. Log in to delivery.zenoss.io and download the Analytics RPM packages for your operating system.

   CentOSRHEL

   • zenoss-analytics-6.0.0-1.el7.x86_64.rpm
   • zenoss-analytics-mysql-plugin-1.0.2-1.el7.x86_64.rpm

   • zenoss-analytics-6.0.0-1.el8.x86_64.rpm
   • zenoss-analytics-mysql-plugin-1.0.2-1.el8.x86_64.rpm

   Copy the packages to your Analytics server host.

2. Log in to the Analytics server host as root or as a user with superuser privileges, and then change directory to the directory where the Analytics RPM packages are located.

3. Remove Analytics 5.1.x.

   yum remove zenoss_analytics
   

4. Install Analytics 6.0.0.

   yum install zenoss-analytics-6.0.0-1.el[78].x86_64.rpm
   

   You may see the following error:

   error: unpacking of archive failed on file /opt/zenoss_analytics/conf/catalina.properties;644bdb54: cpio: rename
   

   To recover, remove the file, and then re-run the yum install command.

   rm '/opt/zenoss_analytics/conf/catalina.properties;644bdb54'
   

5. Install the MariaDB plugin.

   yum install zenoss-analytics-mysql-plugin-1.0.2-1.el[78].x86_64.rpm
   

6. Run the plugin setup script as user zenoss.

   su - zenoss
   /opt/zenoss_analytics/bin/setup_zenoss_extensions install
   

   On success, the script returns Function 'percentile' is already installed. Proceed to step 7.

   On failure, perform the following substeps.

   1. If you get a credentials error, re-run the script and provide the password for the MariaDB root user.

      /opt/zenoss_analytics/bin/setup_zenoss_extensions -p install
      

      Enter root’s password when prompted.

      • If the script succeeds, proceed to step 7.
      • If the script fails, continue with the following substeps.

   2. Stop the Analytics server and then restart MariaDB.

      sudo systemctl stop zenoss-analytics && sudo systemctl restart mariadb
      

   3. Verify the plugin is working.

      /opt/zenoss_analytics/bin/setup_zenoss_extensions check
      

      If you get a credentials error, re-run the script and provide the password for the MariaDB root user.

      /opt/zenoss_analytics/bin/setup_zenoss_extensions -p check
      

      Enter root’s password when prompted.

      On success, the script returns a result similar to the following:

      Function 'percentile' is already installed
      

7. Exit the zenoss shell.

   exit
   

8. Update systemd.

   systemctl daemon-reload
   

9. Enable and start the Analytics server.

   systemctl enable zenoss-analytics && systemctl start zenoss-analytics
   

Update or remove ZenPacks

To complete your update, install the new ZenETL ZenPack and remove the ZenossAnalyticsMonitoring ZenPack.

• Download the new ZenETL ZenPack from delivery.zenoss.io and then follow the standard ZenPack installation procedure to install it.

• Follow the standard ZenPack removal procedure to remove the ZenossAnalyticsMonitoring ZenPack.

Database upgrade error recovery procedure

The output of mysql_upgrade may result in the following error:

ERROR 1932 (42S02) at line 476: Table 'mysql.innodb_index_stats' doesn't exist in engine
FATAL ERROR: Upgrade failed

If so, perform the following recovery steps:

1. Log in to the Analytics server as root or as a user with superuser privileges.

2. Start an interactive session with the mysql client.

   mysql -u root mysql
   

3. Drop the tables that cause the error.

   drop table gtid_slave_pos;
   drop table innodb_index_stats;
   drop table innodb_table_stats;
   

4. Exit the session.

   quit
   

5. Change directory to the MariaDB data directory.

   cd /var/lib/mysql/mysql
   

6. Delete the data files of the dropped tables.

   rm gtid_slave_pos.ibd innodb_index_stats.ibd innodb_table_stats.ibd
   

7. Restart MariaDB.

   systemctl restart mariadb
   

8. Start the database upgrade.

   mysql_upgrade