Chapter 7. Administering WombatDialer

On a CentOS or derived Linux distribution, just run the following commands:

wget -P /etc/yum.repos.d http://yum.loway.ch/loway.repo

yum install wombat

This will in turn:

At the moment we support CentOS 6 and 7. If you run CentOS 5, it is time to upgrade - if you really cannot, please see https://www.queuemetrics.com/faq.jsp?uid=faq-110-java8-centos5

You can install WombatDialer within any working servlet container version 2.5 or newer - we suggest Tomcat 8.5. You will also need a working MariaDB or MySQL server. OpenJDK 8+ is fine.

apt-get install tomcat8 mariadb-server

cd /var/lib/tomcat8/webapps/
wget ..../WombatDialer-18.08.1-215.tar.gz
tar zxvf WombatDialer-18.08.1-215.tar.gz
mv wombatdialer-18.08.1/ wombat/

cd /var/lib/tomcat8/webapps/wombat/WEB-INF/DB
mysql < wombat_create.sql
mysql -uwombat -pdials wombat < wombat_schema.sql

service tomcat8 restart

When installation is done, connect to http://myserver.address:8080/wombat - you will be asked for the MySQL root password to create a local database When done, login using as user demoadmin password demo.

WombatDialer ships with a free demo key that lets you use up to two lines - no limit on the number of calls you make. You may want to get a free demo key so you can run a full evaluation of the software in a real-life scenario.

License keys can be installed from the License page Section 4.8, “The License page” as soon as you log in.

If you plan to use e-mail notifications, you should edit the tpf.properties file to tell WD about your SMTP servers and the e-mail address it is supposed to use.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_AUTH=yes
SMTP_USER=your-gmail-account@gmail.com
SMTP_PASSWORD=wombat
SMTP_USE_SSL=no
SMTP_FROM="WombatDialer" <your-gmail-account@gmail.com>
SMTP_DEBUG=yes

As e-mail sending happens on the notification thread, a very slow SMTP server might delay HTTP notifications. In this case, we suggest setting up a local SMTP relay that will immediately accept e-mail and will forward it to the "true" SMTP host.

We suggest leaving SMTP_DEBUG on during the initial setup as it writes a verbose log of all SMTP activity on the logs and lets you spot errors and issues quickly.

Docker is an open-source project that automates the deployment of applications inside software containers, by providing an additional layer of abstraction and automation of operating system-level virtualization on Linux.

When you have Docker installed, starting a temporary instance of WombatDialer is as simple as typing:

docker run -p 8080:8080 -d loway/wombatdialer

This will download the current WombatDialer (already pre-configured for you) and will run it by exposing it on the local port 8080.

The problem with this approach is that when the image is terminated, all data is lost.

A better approach would be to create a data-only container to store the data. At this point, every time you start WombatDialer, it looks for its own data into the data-only container.

You start by creating a named data-only container:

docker run --name=MYWBT loway/data true

At this point, you can run WombatDialer using that container, as in:

docker run --volumes-from MYWBT -p 8080:8080  -d loway/wombatdialer

WombatDialer will recognize whether the data container is blank and will initialize it properly. The container also monitors the health of the running WombatDialer process and will restart it as needed.

If you prefer, you may use a local folder instead of a data-only container, as in:

docker run -v /root/WBT1DATA:/data -p 9090:8080 -d loway/wombatdialer

This command mounts the local folder /root/WBT1DATA for WombatDialer to store its data in, and - for a change - will expose WombatDialer on port 9090.

You can also control the local time-zone and the amount of memory used, by passing them as parameters when starting up the image:

docker run -e CFG='{"memory":400,"timezone":"GMT"}' -p 8080:8080 -d loway/wombatdialer

When you need to upgrade WombatDialer - you simply stop the current image and start a new one using the same data container. Your dialer is updated!

If you originally installed via yum, this should be enough:

yum update wombat

System settings should be automatically transferred.

When the update is complete, on the first connection you might be asked to upgrade the database - the dialer will not start until the database is up to date. Database upgrades will be applied automatically.

	If after an upgrade you get an error like java.util.MissingResourceException: Can't find bundle for base name org.eclipse.jdt.internal.compiler.problem.messages, this means that there are cached classes created with a different version of the JDK.

You can have them flushed by issuing the commands:

service qm-tomcat6 cleancache
service qm-tomcat6 start

When the update is complete, on the first connection you might be asked to upgrade the database - the dialer will not start until the database is up to date. Database upgrades will be applied automatically.

The dialer will usually start automatically when the webapp is loaded. Exceptions to this behavior happen if:

If you prefer to avoid the dialer starting automatically, you can do this by creating a flag file called 'donotstart' to be placed under WEB-INF, like e.g.

touch ./WEB-INF/donotstart

In order to revert to the previous behavior, simply remove the flag file.

In order to diagnose problems with WombatDialer, it may be needed to take thread dumps by running:

/etc/init.d/qm-tomcat6 threaddump > dump_2013-01-18.txt

These dumps prints what the threads are doing at a point in time. It may be worthwhile to take multiple ones, a few minutes apart from each other.

In order to diagnose problems with WombatDialer, it may be needed to take TCP dumps:

First off you can check your network interfaces by typing:

tcpdump -D

the result will be something like

1.eth0
2.any (Pseudo-device that captures on all interfaces)
3.lo

Issue the dump on port 5038 (remember to add the -s option to avoid capturing only packet’s headers)

tcpdump -i lo -s 65535 -w dump.pcap port 5038

This will generate a file called dump.pcap which can be analized using Wireshark.

On request, you may need to create a heap dump. This is a large file containing the full contents of the live JVM.

[root@wombat1 ~]# /usr/local/queuemetrics/java/bin/jps
1900 Jps
30808 Bootstrap

The line containing Bootstrap contains the PID of the Java VM running Tomcat.

[root@wombat1 ~]# /usr/local/queuemetrics/java/bin/jmap -F -dump:live,format=b,file=heap.bin 30808
Attaching to process ID 30808, please wait...
Debugger attached successfully.
Server compiler detected.
JVM version is 17.1-b03
Dumping heap to heap.bin ...
Finding object size using Printezis bits and skipping over...
Finding object size using Printezis bits and skipping over...
Finding object size using Printezis bits and skipping over...
Finding object size using Printezis bits and skipping over...
Finding object size using Printezis bits and skipping over...
Heap dump file created

The resulting file (called heap.bin as specified on the command line) might be very large and it might take a while to create on busy systems with large Java heaps.

Before sending the file over it is better to compress it:

[root@wombat1 ~]# ls -l heap.bin
-rw-r--r-- 1 root root 40779016 Jan 10 08:45 heap.bin
[root@wombat1 ~]# bzip2 heap.bin
[root@wombat1 ~]# ls -l heap.bin.bz2
-rw-r--r-- 1 root root 8055474 Jan 10 08:45 heap.bin.bz2

Edit the my.cnf file (usually in /etc/mysql/my.cnf). Look for the section called "Logging and Replication".

#
# * Logging and Replication
#
# Both location gets rotated by the cronjob.
# Be aware that this log type is a performance killer.

log = /var/log/mysql-all-queries.log

Just uncomment the "log" entry to turn on logging. Restart MySQL with this command:

service mysql restart

Edit file my.cnf and add the following parameters:

[mysqld]
log-slow-queries=/var/log/mysql-slow-queries.log
long_query_time = 2
log-queries-not-using-indexes

This will log all queries taking more than two seconds or running without a defined index to the slow queries log.

Then restart MySQL.

In order to manage WombatDialer’s database size, a clean-up script is included in WombatDialer’s installation package. The script file can be found in the application folder at the following path:

WEB-INF/DB/cleanup_wbt.sh

Before you run this script make sure you give it the appropriate permissions it needs to be executed.

This script, when executed, searches for old data that is no longer useful or has been hidden by the user. To decide how old must this data be in order for it to be deleted, the user must input a date that will be considered its clean-up treshold.

There are two areas where data can be deleted:

When all the data has been erased, the script will initiate a procedure to rebuild all tables and indexes, thus optimizing and improving database access times.

	Please note that in order to succesfully run this script, WombatDialer must be turned off before running it. On a multi-gigabyte database, plan a few hours of possible downtime.

	Running this script will cause some data to be deleted permanently. It is possible for the script to leave the database in an inconsistent state. It is mandatory that you make a backup copy of your database before running this script.

After navigating to the correct folder and setting the appropriate permissions to the script file, you can execute it by typing:

./cleanup_wbt.sh -u wombat -p dials -d wombat -t 2017-12-31 -m all

As you can see, we need to input five parameters to execute the script. These parameters are all mandatory except for one:

There are five different modes for the script:

We suggest manually running the script as preview first; then delete and then optimize.