Upgrading USS Gateway

Updated 10 months ago by admin

From time to time, updates to the USS Gateway core software and operating system are released. You will be notified when logging in to the USS Gateway web interface of any new core software updates. It is best practice to keep your gateway up to date with the latest release.

From version 1.1, the USS Gateway is based on the Ubuntu 16.04 operating system. All customers are advised to upgrade (see steps below) before April 2019 after which Ubuntu are ceasing security updates for the 14.04 operating system.

Upgrading 1.1.x (Ubuntu 16.04 based)

To upgrade the USS Gateway software and operating system:

Web access will be interrupted during the upgrade process. If you are unsure, please contact your Service Provider
  1. Log in to the Command Line
  2. Prior to Gateway version 1.2.x, if you have created any custom Squid configuration overrides then you must back these up manually before you begin the upgrade, and restore them afterwards (step 7).
sudo cp /usr/local/uss-squid4/etc/squid.conf.override squid.conf.override.old
sudo cp /usr/local/uss-squid4/etc/squid.conf.pre-override squid.conf.pre-override.old
  1. At the prompt, enter sudo apt-get update && sudo apt-get dist-upgrade and press Enter
  2. Enter your superuser password
  3. Enter Y when prompted to install the new packages
  4. Follow any further prompts and accept any defaults if asked
  5. After the process has finished, if you backed up any Squid configuration override files in step 2, you can now restore them.
sudo cp /usr/local/uss-squid4/etc/squid.conf.pre-override.old squid.conf.pre-override
sudo cp /usr/local/uss-squid4/etc/squid.conf.override.old squid.conf.override
Once the update has completed, you may perform a reboot - however this is not a mandatory step

Upgrading from 1.0.x to 1.1.x

The new 1.1.x (and higher) version of the USS Gateway is based on the Ubuntu 16.04 operating system and includes numerous new features and performance optimisations.

There are two methods for upgrading the USS Gateway. If you are unsure, please seek advice from your service provider.

  • Reinstall to upgrade
  • Upgrade an existing 1.0.x version manually - the advantage of this method is that the Active Directory configuration is preserved

Upgrading with the standard reinstall procedure

This reinstall procedure is for customers wishing to upgrade from 1.0.x to 1.1.x of the USS Gateway software . The alternative is to upgrade an existing v1.0.x installation to v1.1.x without a reinstall (see below).

Important Considerations

If you use a physical machine for the USS Gateway, you will need to consider that upgrading to 1.1.x will require a reinstall of the operating system. It is recommended that you schedule the upgrade to minimise downtime for end-users, as the proxy will be offline whilst you reinstall the software. The estimated time for the upgrade procedure is 30-60 minutes.

If you use a virtual machine environment, the best practice is to create a new virtual machine for the 1.1.x-based proxy, and then swap end-users when configuration is complete.

To perform a reinstall
  1. On your existing USS Gateway, follow the first part of the article Migrating the SSL Intercept certificate to a new server and store the .pem somewhere safe.
  2. If you have customised the USS Gateway using the advanced override scripts, take a copy of the contents of each of the files and store them somewhere safe.
  3. Make a note of the Active Directory configuration if you are using Kerberos Authentication. You will need to join the new proxy to the domain after installation.
This part of the configuration cannot be transferred to the new gateway.
  1. Download the 16.04 ISO image
  2. Install the USS Gateway software from ISO
  3. Link the new gateway to your USS cloud account
  4. If your old gateway was using a Configuration Profile other than the default one, then assign the correct configuration profile to the new gateway. Use the Update Config button to download the latest configuration profile, or wait 15 minutes for the gateway to automatically update.
  5. Follow the second part of the article Migrating the SSL Intercept certificate to a new server and import the .pem from Step 1.
  6. If you followed Step 2, restore the override scripts on the new gateway and restart ussgw-sysmond (e.g. /etc/init.d/ussgw_sysmond stop; /etc/init.d/ussgw_sysmond start )
  7. If you followed Step 3, re-join the gateway to the Active Directory domain and ensure you create the new encryption keys.
  8. Test the new gateway for authentication and SSL interception before switching end-users to the new proxy.

Performing a manual upgrade

It is possible to upgrade an existing USS Gateway based on Ubuntu 14.04 to 16.04 without reinstalling the operating system. This procedure requires familiarity with the Linux command line.

This is an advanced guide and familiarity with the Linux command line (the shell) is required. Please ensure you follow the backup steps so that in the case of failure, it is still possible to reinstall the USS Gateway to its original state.
If any of the steps below result in an error message that is not covered in the guide, seek advice from your service provider before continuing.

Before proceeding:

  1. On your existing USS Gateway, follow the first part of the article Migrating the SSL Intercept certificate to a new server and store the .pem somewhere safe.
  2. If you have customised the USS Gateway using the advanced override scripts, take a copy of the contents of each of the files and store them somewhere safe.

To begin, log in to the USS Gateway command line console. The first step is to ensure your current gateway has all of the latest updates applied. Run the following commands to ensure that your gateway is up to date:

sudo apt-get update

sudo apt-get dist-upgrade

sudo reboot

It is important to use dist-upgrade and it is important to reboot afterwards to install any new kernel updates.

Next, configure the update manager to use the LTS (Long Term Support) version of Ubuntu 16.04. To do this, run:

sudo nano /etc/update-manager/release-upgrades

Scroll down to the line that starts Prompt= and set the value to lts. The result on screen should look like the screenshot below:

The lts value is case-sensitive, so it must be lts, rather than LTS or Lts.

Save the file and exit the editor (Ctrl+X then Y then Enter if using nano).

Next, run the following command:

do-release-upgrade -c

This will check for any available upgrades and display the version.

If the version shown is not 16.04 then do not continue. Seek advice from your service provider.

You should see the following:

To begin the upgrade, run the following command:

do-release-upgrade

The following message will be displayed:

This means that you've actually disabled the package repository for the USS Gateway. This is intentional. You'll resolve this later in this guide.

Press Enter to continue.

After a few moments the following message will be displayed:

Press Y and then press Enter. Wait for the download to complete and for the upgrade to begin.

At the following prompt, select NO (if required, use the Tab key to switch buttons and Enter to confirm).

Next, you will see the following message. Press Enter to accept the default:

Next you will be prompted a number of times with messages like the example below. Accept the defaults by pressing N and then Enter for each message.

After a while, the following message will be displayed. This issue will be resolved later in the guide. For now, press Enter to continue.

One the next screen, select Install the package maintainer's version and then use the Tab key to select OK and press Enter.

Once the package analysis completes, the following prompt will be displayed:

Press Y and then Enter.

This will actually remove the USS Gateway software packages. This is intentional: the configuration will remain in place.

The upgrade will continue.

The upgrade may take a long time.

Once the upgrade is complete, you will be prompted to reboot. Press Y and then Enter.

It may take several minutes for the machine to reboot after pressing Y. This is normal.

You may see warning/error messages such as the ones shown in the screenshot below - these can be safely ignored.

After the reboot, log in to the console again to continue the process.

The next step is to install the USS Gateway packages for Ubuntu 16.04. To do this, it is necessary to update the apt repository sources.

At the console prompt, type:

sudo nano /etc/apt/sources.list

Scroll to the end of the file and add the following line:

deb http://apt-xenial.clouduss.com xenial non-free

The result on screen should look like the screenshot below:

Save the file (Ctrl+X then Y then Enter if using nano) and then run:

sudo apt-get update

Next, install the latest USS Gateway software package:

sudo apt-get install ussgateway

sudo reboot

The final step is to fix the Postgres 9.3 warning that was displayed earlier in the upgrade process. To do this, run the following commands:

sudo /etc/init.d/nginx stop

sudo /etc/init.d/uss-squid stop

sudo /etc/init.d/ussgw_sysmond stop

The next step is to disable the unnecessary Postgres 9.5 cluster that was created during the upgrade, and promote the original 9.3 cluster in its place. The final step removes the old 9.3 cluster, which is no longer needed.

sudo pg_dropcluster 9.5 main --stop

sudo pg_upgradecluster 9.3 main

sudo pg_dropcluster 9.3 main

The last step of the upgrade is to reboot the USS Gateway to ensure that everything starts up as expected:

sudo reboot

You should now be able to access the local UI for configuration. We recommend clearing your browser cache to ensure you are using the latest version of the UI.

The upgrade procedure is now complete.

How did we do?