Upgrading from Previous Versions

Warning

Perform non planned upgrades only if you are having serious issues with your current version of the product or you are told to do so by the Support Team. In all other cases continue using your current version and plan routine upgrade at a later date. Beware upgrade process is error prone and fragile due to the complexity of the application and a lot of integration points with Squid and OS so it does not always go smoothly. Backup before upgrading!

Preliminary Notes

In order to upgrade your current installation of Web Safety ICAP Server to version 5.0 follow these steps.

Save your current configuration to a temporary location

#!/bin/bash

set -e

# check we are root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root" 1>&2
   exit 1
fi

# we are going to copy the files from /opt/qlproxy/etc to this folder
cp -rf /opt/qlproxy/etc/ ./data/

# just in case we also store the databases here
cp -rf /opt/qlproxy/var/db/ ./data/

echo "Copied all files from /opt/qlproxy/etc/ successfully"

Reinstall versions of Web Safety

If you are currently using virtual appliance (VA) the best way to upgrade is to first export configuration from old VA as described above, get a new VA from our site, import the settings into the new VA as described below and only when you are sure the new VA works as expected, decomission the old VA. This will let you go back to a proved working solution in case something gets wrong!

If you are not using virtual appliance and your proxy is running on real hardware you now need to manually uninstall old version of Web Safety by running dpkg --remove qlproxy && dpkg --purge qlproxy (Debian/Ubuntu) or rpm -e qlproxy (RedHat/CentOS). Do not forget to clear or copy to some temporary location the /opt/qlproxy folder afterwards.

Warning

There were a lot of breaking changes in 5.0 compared to 4.X versions. If you run Web Safety on real hardware it is recommended to completely rebuild the proxy box from scratch. See Version History for more information!

Now install latest version of Web Safety according to instructions for specific operating systems.

Import previously stored configuration from temporary location

#!/bin/bash
set -e

# check we are root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root" 1>&2
   exit 1
fi

# import all data
python /opt/websafety/var/console/upgrade.py --etc_dir=/full/path/to/data/dir/described/above --version=4.9

# now MANUALLY copy over other files from ./data if needed (html, key, der, pem)

# and reset the owner just in case
chown -R websafety:websafety /opt/websafety

Please adjust the --version=4.9 argument if you are upgrading from on older version. Supported versions are 4.2, 4.3, 4.4, 4.5, 4.6, 4.7 and 4.8. Not every item from older version may be upgraded. Please also adjust the full path to the folder to import.

After import is complete, manually copy the all files (except JSON) from your data folder to the /opt/websafety/etc, overwriting those that exist there.

Limitations of the upgrade

  • Unfortunately we cannot upgrade the collected traffic in monitoring database.
  • Due to the reason above configured reports are not upgraded. Please reconfigure them manually after install of new version.
  • Squid authentication settings are only partially upgraded. Please manually reconfigure Active Directory integration if it was configured before.
  • Credentials for the root user in Admin UI are reverted to default. All users added to Admin UI are lost.
  • You may need to manually re-import existing license key, RootCA certificate and keytab file into Admin UI again.