USS Gateway Version 1 to Version 2 Migration

How to Migrate from version 1 to version 2 USS Gateway

Download a PDF copy of this guide

The new USS Gateway 2 version is built on the recent 20.04 Ubuntu OS, which means there is no direct update path from the current version (16.04) as we skip the entire 18.04 OS release.

This means the upgrade process requires the user to setup and install a new USS gateway server. This will then take over from the old USS gateway. For a successful upgrade, please follow the steps below:

1. Installing the new Gateway 2

Install a new 20.04 virtual machine (or bare metal server) on a place- holder IP and hostname (this will be changed later).

2. Root CA

Extract the root CA from the old 16.04 gateway and import into the new 20.04 gateway, this is important to make sure users don’t see a certificate error when the migration is complete.

Install Setup How to Root CA

Your USS gateway might have custom configuration set by you, your IT provider or the Censornet team. If this is the case, please make a copy of the squid. The files are available in these locations on the USS gateway server in the following locations:

/usr/local/uss-squid4/etc/squid.conf.override /usr/local/uss-squid4/etc/squid.conf.pre-override

You can access them by running the following commands from the command line sudo su

nano /usr/local/uss-squid4/etc/squid.conf.pre-override [or] squid.conf.override

You can then just copy and paste the contents into these files on the new server. If they are empty, no further action is required. If not empty, restart by clicking 'Restart Proxy' within the Platform Settings.

NOTE: this next part if done correctly should only take about 10 minutes
4. Remove the Old Gateway

Delete or power off the 16.04 gateway (power-off recommended). This is crucial to avoid an IP conflict.

5. Hostname

Change the hostname of the (new) 20.04 gateway to match the (old) 16.04 gateway. Next, change the interface IP to match the (old)16.04 gateway. The order of change is important. After changing the hostname, please reboot the gateway.

6. Active Directory

Set up AD authentication on the (new)20.04 gateway.

For ease, take a screen-shot of the existing AD configuration on the (old) 16.04 USS Gateway so that you can fill in the details exactly the same.

A set of AD admin credentials is necessary for this step. End-users might need to log out and back in for authentication to start working due to a change in the Kerberos ticket.

If you use a custom proxy.pac which is hosted, please continue reading. If not, your migration is now complete.

ADDITIONAL INFO FOR A CUSTOM PROXY.PAC (ONLY APPLICABLE IF YOU USE CUSTOM PAC FILE):

If you have a custom proxy.pac file here’s a guide on how to import it into the new gateway. Standard files need no further action.

Open Putty or any console connection to the USS gateway and run the following commands on the new server:

sudo su

nano /var/www/proxy.pac

Proceed to copy and past the new proxy.pac or edit the existing. CTRL + X to save and exit

chattr +i /var/www/proxy.pac

NOTE: the chattr +i command locks the file for editing. If you want to edit it again you’ll need to unlock it by running the same command but changing it to chattr -i

Alternatively if your pac file has a customised name you can just create it directly in the directory with these commands:

sudo su

nano /var/www/name-of-file.pac

[then paste the contents and ctrl + X to save an exit]

From this point on the new gateway would take over from the old gateway and end users should regain Internet access.

How did we do?