How do I upgrade ZXTM AFM 3.0 to Zeus Application Firewall Module 3.1?

Zeus Application Firewall Module 3.1 provides much tighter integration with the Zeus Traffic Manager, making it easier to manage than 3.0. If you have an existing installation of 3.0 and want to upgrade, this must be done via a backup and uninstall. This article will walk you through the process.

In line with the renaming of ZXTM to Zeus Traffic Manager, ZXTM AFM has been renamed to Zeus Application Firewall Module.

Requirements

You will need:

• The correct Zeus Application Firewall Module 3.1 package for your platform.
• Suitable Zeus Application Firewall Module license keys for all your machines.
• Knowledge of which ZXTM AFM installation is currently the "master" of the cluster (check the ZXTM AFM administration interface).
• Either a few minutes in which you can run your services unprotected, or a few minutes in which your services can refuse requests.

Correct ZXTM AFM 3.0 cluster configuration

On the ZXTM AFM master, visit the ZXTM AFM administration interface, go to the "Cluster Configuration" section and ensure the cluster master refers to itself by an IP address that is reachable from the other ZXTM AFM installations, not 127.0.0.1. Check that slaves are listed as reachable IP addresses and not 127.0.0.1. Also, edit the zxtmafm.conf file, replacing any instances of 127.0.0.1 with 0.0.0.0. Then restart ZXTM AFM on that machine.

Take a backup

The upgrade can not be performed in-place, because ZXTM AFM 3.0 was installed using your operating system's package manager. Zeus Application Firewall Module 3.1 is installed as a module in Zeus Traffic Manager. Therefore, you must take a backup of your ZXTM AFM configuration (and store it somewhere outside $ZEUSHOME) before proceeding. There are some inaccuracies in the backup page of the 3.0 documentation; to create a sufficient backup, do the following on whichever machine is currently the master of the ZXTM AFM 3.0 cluster. Note that the 3.0 package will have been installed into /opt/zeus even if your traffic manager is installed elsewhere.

BACKUP=/root/afm30backup
mkdir $BACKUP
cp -p /opt/zeus/zxtmafm/current/etc/zxtmafm.conf $BACKUP/
cp -pR /opt/zeus/zxtmafm/current/var/lib $BACKUP/varlib
cp -pR /opt/zeus/zxtmafm/current/var/log $BACKUP/varlog
cp -pR /opt/zeus/zxtmafm/generic/log $BACKUP/
cp -pR /opt/zeus/zxtmafm/generic/log-master $BACKUP/

You may also wish to back up your Zeus Traffic Manager configuration, as documented in the Zeus Traffic Manager User Manual.

Upgrade Zeus Traffic Manager

Upgrade to Zeus Traffic Manager 6.0 or later, and ensure it is properly licensed. Zeus Application Firewall Module 3.1 is not compatible with older Zeus products. See your Zeus Traffic Manager Getting Started Guide for instructions.

Disable ZXTM AFM Enforcer Rule

In order to minimise downtime, disable the ZXTM AFM Enforcer Rule on each virtual server (remembering to disable it both for requests and for responses). Your services will be unprotected from this point until the upgrade is complete. You may instead leave the rule enabled and your services will be unavailable until the upgrade is complete.

Uninstall ZXTM AFM 3.0

This will also delete your configuration, so ensure you have taken a backup first.

On each cluster member, using your operating system's package manager, remove the zxtmafm package. This can be done using dpkg -P zxtmafm on Debian-based systems, rpm -e zxtmafm for RPM-based systems and pkgrm zxtmafm on Solaris. You may see warnings about directories not being empty and therefore not being removed; these can be safely ignored.

Install Zeus Application Firewall Module 3.1 on the former master node

On the former ZXTM AFM master, visit the System > Upgrade page and upload the Zeus Application Firewall Module 3.1 package. You should upload the package file (e.g. Zeus_AFM_3.1.2-13847_Linux-x86_64.tgz ) as you received it, without extracting it. You will be asked to set a password and confirm the installation, and you should then see a statement that the installation was successful and a link to the settings page. If you see errors instead, record them and contact your support provider.

Do not make changes to the configuration at this stage; you will lose them in the next step. Note that after you restore your configuration in the next step, your password will be what it was before the upgrade, and not the one you create here.

At this point Zeus Application Firewall Module is running, but without your configuration. To restore the configuration you backed up in the first stage of these instructions, first stop Zeus Application Firewall Module using $ZEUSHOME/service.sh zeusafm stop and then copy the files from your backup, using the following commands. If you are not using an appliance, you must manually set ZEUSHOME first.

BACKUP=/root/afm30backup
$ZEUSHOME/service.sh zeusafm stop
cp -fp $BACKUP/varlib/* $ZEUSHOME/zeusafm/current/var/lib/
cp -fp $BACKUP/varlog/* $ZEUSHOME/zeusafm/current/var/log/
[ "x`ls $BACKUP/log/`" != "x" ] && \
cp -fp $BACKUP/log/* $ZEUSHOME/log/zeusafm/log/
[ "x`ls $BACKUP/log-master/`" != "x" ] && \
cp -fp $BACKUP/log-master/* $ZEUSHOME/log/zeusafm/log-master/

Note that you must not copy zxtmafm.conf from the backup. If required, add individual settings to $ZEUSHOME/zxtm/conf/zeusafm.conf at the end of these instructions.

Start Zeus Application Firewall Module again using $ZEUSHOME/service.sh zeusafm start (this will upgrade your configuration to be suitable for 3.1). At this point, you have one machine running Zeus Application Firewall Module 3.1 with your restored configuration.

Install Zeus Application Firewall Module 3.1 on the remaining machines

On each remaining machine, visit the System > Upgrade page, upload the package and provide the Zeus Application Firewall Module username and password. Each machine will join the cluster during installation.

Clean up

On each cluster member, visit the "System > AFM" page and check the "Zeus AFM Cluster" section. If you are prompted for the username and password to join this installation to the cluster, do so.

On any cluster member, visit the Zeus Application Firewall Module administration interface. You will find the SSL certificate has changed to the one used by the Zeus Traffic Manager administration interface, which may result in a warning from your web browser. Also, if the page layout there seems incorrect, your browser may have cached old versions of some images and stylesheets; a forced browser reload should correct the problem. Go to the License Management section and check you have the correct licenses present for Zeus Application Firewall Module 3.1, if not, upload them.

As of version 3.1, the Enforcer Rule is installed automatically and configured differently from in previous versions. For each virtual server, enable the Application Firewall setting in the virtual server's Basic Settings section and remove any previous Enforcer Rule (from request rules and from response rules). You should then delete any previous versions of the Enforcer Rule, as they should not be used with Zeus Application Firewall Module 3.1. The automatically-installed rule is called "Zeus AFM Enforcer". If your previous rule had the same name, the upgrade will have backed it up in a dot-file. You should also remove any pool and virtual server you created to balance across multiple deciders. They will no longer be used; Zeus Traffic Manager 6.0 will balance across multiple deciders automatically.

Notes

You should check that Zeus Application Firewall Module is working correctly. See the Zeus Application Firewall Module documentation for a summary of the changes in this version.

Zeus Application Firewall Module 3.1 will be started and stopped automatically by the start-zeus and stop-zeus scripts, including at boot time and shutdown (if you have configured Zeus Traffic Manager to start at boot).

Chris Boyle [Zeus Dev Team] 26 October 2009