USS Gateway Version 1 to Version 2 Migration
How to Migrate from version 1 to version 2 USS Gateway
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
3. Custom Configuration (Optional but recommended)
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:
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.
4. Remove the Old Gateway
Delete or power off the 16.04 gateway (power-off recommended). This is crucial to avoid an IP conflict.
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.
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:
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:
[then paste the contents and ctrl + X to save an exit]