Upgrading QueueMetrics used to be a matter of running yum update. This is no longer the case: the yum repository is not available anymore and QueueMetrics is now installed as a standalone package, with its own installer and a single configuration file. This tutorial shows the recommended way to upgrade: set up a brand new server with the current packages, and migrate only the database to it.

How to upgrade QueueMetrics by migrating to a new server

The old RPM installation was built around Tomcat and the files under /usr/local/queuemetrics/qm-current/WEB-INF. The current QueueMetrics is a standalone application that runs on a modern Java (Java 25), uses MySQL or MariaDB for its data, is installed in /opt/loway/queuemetrics/ and is configured through one file, /etc/default/queuemetrics.

Because the whole software stack changes, we recommend not upgrading the old machine in place. Instead:

  • you prepare a new server with the packages listed in the documentation;
  • you copy over the database, which holds all your queues, agents, users, QA forms and settings;
  • you point Uniloader at the new server and switch off the old one.

This is also the safest way to do it: the old server is left untouched until the very end, so you can go back to it at any moment.

What you need

  • Your current QueueMetrics installation, which keeps running while you prepare the new one
  • A new server (physical, virtual or a cloud instance) running a supported Linux distribution with systemd: RHEL 9/10 and derivatives (AlmaLinux, Rocky Linux, Oracle Linux), Debian 11/12/13, Ubuntu 22.04/24.04/26.04 LTS, SUSE Linux Enterprise Server 15 SP7 or 16, Fedora, Arch Linux or Gentoo
  • Root access to both servers
  • Outbound Internet access from the new server, as QueueMetrics needs it for license validation. If you need a proxy, it can be configured in the main configuration file.
  • Your license key (see Step 1)
  • A short maintenance window: no data reaches QueueMetrics while the final copy is made

TIP: this tutorial also works if you just want to move QueueMetrics to a new machine, even if you are already on the standalone version.

Step 1 - Collect what you need from the old server

On the old server, gather these three things before you touch anything.

The license code. It is needed to install your license on the new system:

grep LICENZA_ARCHITETTURA /usr/local/queuemetrics/qm-current/WEB-INF/tpf.properties

The database connection string, only if QueueMetrics uses a remote database:

grep JDBC_URL /usr/local/queuemetrics/qm-current/WEB-INF/tpf.properties

Any custom Java settings. Memory changes are usually found in the JAVA_MEM variable:

cat /etc/sysconfig/qm-tomcat6

Keep a copy of the output: you will re-apply these values on the new server.

NOTE: a license key must not run on more than one system at the same time. If the key is used on two servers, it may be blocked and a reactivation fee may apply. This is why the old QueueMetrics is stopped before you start the new one (Step 6).

Step 2 - Prepare the new server

Install Java 25, MariaDB (or MySQL, any currently supported version) and a few basic tools. The package names depend on the distribution. For example:

On RHEL 9/10 and derivatives:

dnf install -y java-25-openjdk-headless mariadb-server tar gzip nano
systemctl enable --now mariadb

On Ubuntu 22.04 / 24.04 / 26.04:

apt-get update
apt-get install -y openjdk-25-jdk-headless mariadb-server tar gzip nano

On Debian 13:

apt-get update
apt-get install -y openjdk-25-jre-headless mariadb-server tar gzip nano

On SUSE Linux Enterprise Server:

zypper --non-interactive refresh
zypper --non-interactive install java-25-openjdk-devel mariadb tar gzip nano
systemctl enable --now mariadb

NOTE: some older distributions (Debian 11 and 12, Ubuntu 20.04) do not ship Java 25 in their repositories. For these you need to add the Eclipse Adoptium repository first and install temurin-25-jdk instead. For Fedora, Arch Linux and Gentoo, see the Installing QueueMetrics page of the documentation, which lists the exact commands for each distribution.

Step 3 - Install QueueMetrics on the new server

The quickest way is the install script, run as root:

curl -sL get.queuemetrics.com | bash

If you prefer to install a specific version, download the .tar.gz archive from the Loway downloads site and run the installer from it. For example:

tar zxvf QueueMetrics-26.10.3-standalone.tar.gz
cd QueueMetrics-26.10.3
./install.sh

The installer puts QueueMetrics in /opt/loway/queuemetrics/, creates the queuemetrics user and group, writes the configuration file /etc/default/queuemetrics and, if MySQL root access works without a password, creates an empty queuemetrics database.

Check that it is up:

queuemetrics-cli status

Then open http://<your-new-server>:8080/queuemetrics. You should see the login page of a brand new, empty QueueMetrics (the default login is demoadmin / demo). This confirms that Java, the database and the application work, before any of your data gets in the way.

Now stop it, as we are about to replace its database:

queuemetrics-cli stop

Step 4 - Back up the database on the old server

This is the actual migration step. To be sure that the dump is complete, no new data must be written while you take it, so stop Uniloader on the PBX first:

service uniloader stop

If you still use the older Qloaderd instead of Uniloader, stop that one (service qloaderd stop). You can check which one is running with ps fax | grep loader.

Then, on the old QueueMetrics server, stop the application and dump the database:

service queuemetrics stop
mysqldump queuemetrics | gzip > queuemetrics.sql.gz

If your MySQL needs credentials, add them as usual, for example mysqldump -uroot -p queuemetrics.

Copy the dump to the new server, for example with scp:

scp queuemetrics.sql.gz root@<your-new-server>:/root/

TIP: keep this file. It is your backup if anything goes wrong, and the old server still holds all the data as well.

WARNING: do not run yum remove queuemetrics on the old server to “clean up” before you are sure the new one is working. Removing the old package also removes its database.

Step 5 - Restore the database on the new server

The installer created an empty database. Overwrite it with your dump:

zcat queuemetrics.sql.gz | mysql queuemetrics

Then re-apply your settings in /etc/default/queuemetrics, using the values collected in Step 1:

QM_LICENSE_KEY="....."
QM_JDBC_URI="...."
QM_JAVA_MEM="-Xms1G -Xmx1G"
  • QM_LICENSE_KEY is your license key. If you only have the license code from tpf.properties, ask your Loway contact for the key, or install it later from the License page.
  • QM_JDBC_URI is needed only if the database is not the local one created by the installer.
  • QM_JAVA_MEM is the JVM heap. The default is 1 GB; set a larger value if you were using one on the old server.

The file is well commented, and it also lets you set the listening port (QM_PORT), the listening address (QM_ADDRESS, use 127.0.0.1 if you run QueueMetrics behind a reverse proxy), the log level and directory, the time zone and an outbound proxy. If the settings are all in place, start QueueMetrics:

queuemetrics-cli restart
queuemetrics-cli status

Step 6 - Let QueueMetrics upgrade the database

The first time the new version meets an old database, it will detect it and offer to update it. Open the QueueMetrics address in the browser, log in and follow the database upgrade wizard. On large databases this can take several minutes: let it finish.

You can also run the schema updater by hand with:

queuemetrics-cli dbupdater

or from the DB update utility at http://127.0.0.1:8080/queuemetrics/dbtest/. In both cases, make sure you have a backup of the database first: you already have it from Step 4.

Once done, log in with one of your usual users and check that your queues, agents, users and reports are all there.

If you have not done it yet, check the license on the License page. If it still shows the embedded demo license (limited to two agents, for evaluation), install your key from there with Install new license key, or set QM_LICENSE_KEY and restart.

Step 7 - Switch off the old QueueMetrics

You have already stopped it in Step 4. Make sure it stays off, and in particular that it does not start again at boot:

systemctl disable queuemetrics

Only one server at a time should use your license.

Step 8 - Point Uniloader to the new server

On the PBX, edit the Uniloader configuration so that it sends data to the new server. Use the file that matches your installation (/etc/sysconfig/uniloader on an old RPM installation, /etc/uniloader on a current one):

  • If Uniloader already uses the HTTP/S connection with the webqloader user, just change the address in URI:
URI="http://<your-new-server>:8080/queuemetrics"
  • If Uniloader still writes directly to the MySQL database, it is a good moment to move to the HTTP/S connection instead of adding the usual grants on the new server’s MySQL. The documentation recommends making sure that Uniloader sends data over HTTP/S and not directly to the database. See our tutorial on migrating Uniloader from a MySQL connection to the webqloader user.

Start the service again:

systemctl start uniloader

(or service uniloader start on an old RPM system).

Then check in QueueMetrics, from DBTEST → Live DB inspector, that new lines of the queue_log appear in the database after a couple of seconds.

TIP: if the PBX moves too, install and configure Uniloader on the new PBX as well. The server where the queue_log is generated does not have to be the same as the one that runs QueueMetrics.

Step 9 - Check the remaining connections

A few things depend on the server QueueMetrics runs on, and are worth checking before you go back to normal operations:

  • Asterisk AMI: the new server must be allowed to connect to the AMI of your PBX. You might need to edit the manager user in /etc/asterisk/manager.conf to allow the new address. In clusters, check the property cluster.servername.manager=tcp:user:pass@serverhost. You can test the connection from DBTEST → AMI Tester.
  • Call recordings: the queuemetrics user on the new server needs read access to the audio files. If they are on a network mount, mount it on the new server too. Then add the user to the group that owns the recordings and restart, as group changes only apply to new processes:
usermod -aG <group> queuemetrics
queuemetrics-cli restart
  • Clocks: make sure all the servers involved have their clocks aligned (use NTP).
  • Agents and supervisors: tell them the new QueueMetrics address, and update any bookmark, wallboard or integration (CRM, scripts, API clients) that used the old one.
  • Internet-facing systems: if QueueMetrics can be reached from the Internet, enable secure mode by setting layout.secureMode=true in the system parameters.

Backups and future upgrades

The new installation makes your life easier from now on. To back it up you only need two things: the database dump and the configuration file.

mysqldump queuemetrics | gzip > queuemetrics.sql.gz
cp /etc/default/queuemetrics queuemetrics-defaults-backup

To upgrade to a newer release in the future, take a backup, download the new archive and run the installer again:

tar zxvf QueueMetrics-<version>-standalone.tar.gz
cd QueueMetrics-<version>
./install.sh

The installer keeps your /etc/default/queuemetrics, and the database is upgraded the first time the new version runs. Use queuemetrics-cli version to see which version is currently installed.

If you use Docker, the official loway/queuemetrics image is updated by pulling the new image and re-running the container against the same data folder.

Troubleshooting

  • QueueMetrics does not answer after a few seconds: run queuemetrics-cli status, and look at the log directory set in QM_LOG_DIR. Check that port 8080 (or your QM_PORT) is open in the firewall.
  • The database upgrade is slow: it is normal on large databases. Let it finish, and do not restart the service meanwhile.
  • The license is not accepted: check that the server can reach the Internet (a proxy may be needed), and that the same key is not running on the old server. You can test the connectivity with checkLicenseConnectivity.sh, found under WEB-INF/README/ in the installation.
  • No new data arrives after the switch: check that Uniloader is running and that its URI points to the new server. Look at DBTEST → Live DB inspector and at the Uniloader log.
  • You need to go back: the old server was not touched. Stop the new QueueMetrics, start the old one and point Uniloader at it again.

Once everything works and you have kept your backups for a while, you can decommission the old server.

QueueMetrics References

For more technical information about QueueMetrics call center solution please refer to the User Manual.

About QueueMetrics

QueueMetrics is a highly scalable monitoring software that lets you track agent productivity, payrolls, measure targets, conversion rates, queues/ACDs, IVRs, music-on-hold, generate outbound campaign statistics and monitor realtime processes with customizable wallboards.

You can measure all activities in your contact center with more than 200 different metrics and manage realtime processes with live alarms and full control on calls and extensions, including whisper, spy and barge modes.

QueueMetrics is available on premise or as a cloud hosted service, and it is compatible with FreePBX, Grandstream, Issabel, MiRTA, Enswitch, Yeastar S PBX, VitalPBX, FusionPBX and many other Asterisk- and Freeswitch-based systems. It also supports Microsoft Teams telephony.

For more technical information please refer to the User Manual.

Visit www.queuemetrics.com for a free 15-day full-featured trial.

keyboard_arrow_left Back