Upgrading USS Gateway
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.

Upgrading 1.1.x (Ubuntu 16.04 based)
To upgrade the USS Gateway software and operating system:
- Log in to the Command Line
- 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
- At the prompt, enter
sudo apt-get update && sudo apt-get dist-upgrade
and press Enter - Enter your superuser password
- Enter Y when prompted to install the new packages
- Follow any further prompts and accept any defaults if asked
- 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
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
- 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. - 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.
- 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.
- Download the 16.04 ISO image
- Install the USS Gateway software from ISO
- Link the new gateway to your USS cloud account
- 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.
- Follow the second part of the article Migrating the SSL Intercept certificate to a new server and import the
.pem
from Step 1. - 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
) - If you followed Step 3, re-join the gateway to the Active Directory domain and ensure you create the new encryption keys.
- 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.
Before proceeding:
- 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. - 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
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:

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.
You should see the following:

To begin the upgrade, run the following command:
do-release-upgrade
The following message will be displayed:

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.
The upgrade will continue.
Once the upgrade is complete, you will be prompted to reboot. Press Y and then Enter.
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.