Untangle is a firewall product that I use to manage my network and prevent my kids from accessing certain sites or categories of content. I also use it to shut off internet access to certain devices past certain hours or when I’m given attitude.
Unfortunately, the Home Version of Untangle does not get any support and updates are often promised as “they’ll be pushed out soon.” After rolling with version 12.1 for multiple years, I investigated the upgrade process and have documented the steps I followed to get to the most recent version.
Note: Upgrades MUST be in sequential order. Breaking changes may have been made between versions. Upgrading sequentially will ensure that your current Untangle server and all of its configurations will remain intact. Upgrading out of order may cause you to lose config or worse.
Enable SSH
Please refer to the Untangle Wiki to enable SSH – https://wiki.untangle.com/index.php/Enable_SSH. This is required to edit the apt lists.
Upgrade Path
This is the order in which the Untangle server must be upgraded. Jessie->Jessie and Stretch->Stretch upgrades do not require a restart. The upgrade from Debian Jessie to Debian Stretch will require a reboot.
Jessie
- stihl-2
- beat
- beat-1
- jims
- jims-1
- 13.2.0
- 13.2.1
Stretch
- 14.0.0
- 14.0.1
- 14.1.0
- 14.1.1
- 14.1.2
- 14.2.0
- 14.2.1
- 14.2.2
- 15.0.0
Buster
- 15.1.0
- 15.1.1
- 15.1.2
- 16.0.0
- 16.0.1
- 16.1.0
- 16.1.1
- 16.2.0
- 16.2.1
- See below for issues relating to this version
- 16.2.2
- 16.3.0
- 16.3.1
- 16.3.2
Edit Apt Sources
Untangle Only Upgrade Steps
sed -i “s/$current_version/$next_version/g” /etc/apt/sources.list.d/untangle.list
and bump release code name (or number) to next release- IE. stihl-2 would be
$current_version
and beat would be $next_version
.
- Log into the Untangle UI.
- Select Config -> Upgrade and wait for the system to finish checking upgrades. It should have found a new version and you can click the “Upgrade Now” button.
Distribution Upgrades
Certain upgrade paths require an distro upgrade along with the Untangle upgrade.
- 13.2.1 to 14.0.0 requires upgrading Debian Jessie to Debian Stretch
- 15.0.0 to 15.1.0 requires upgrading Debian Stretch to Debian Buster
Please follow these steps for this one time upgrade and return to the steps above for subsequent upgrades until you hit the next distro upgrade requirement.
sed -i “s/$current_version/$next_version/g” /etc/apt/sources.list.d/untangle.list
and bump release code name (or number) to next release.- IE. 13.2.1 would be
$current_version
and 14.0.0 would be $next_version
.
- For Jessie to Stretch:
sed -i “s/jessie/stretch/g” /etc/apt/sources.list.d/untangle.list
- For Stretch to Buster:
sed -i “s/stretch/buster/g” /etc/apt/sources.list.d/untangle.list
- I’m not sure if this is necessary, but I did it anyways and it did not hinder the upgrades.
- For Jessie to Stretch:
sed -i “s/jessie/stretch/g” /etc/apt/preferences.d/00default-debian.pref
- For Stretch to Buster:
sed -i “s/stretch/buster/g” /etc/apt/preferences.d/00default-debian.pref
- Return to Untangle Only Upgrade Steps to finish upgrading through the versions
Troubleshooting
I’ve seen many times during the upgrade process a page that continually refreshes that says “Upgrade in progress…. Do not reboot.” Please verify that the upgrade is complete before attempting the steps below. You can verify the upgrade by via tail -f /var/log/uvm/upgrade.log
.
Stop the Splash Screen
/usr/share/untangle/bin/ut-show-upgrade-splash stop
If this does not fix the issue, continue to the next step.
Restart Untangle VM
/etc/init.d/untangle-vm restart
14.2.2 -> 15.0.0 Upgrade – Can’t log into Untangle Admin
This is caused by stale cached JS. Reload the page without the cache.
- Windows/Linux: Refresh with SHIFT + F5
- Mac: Refresh with SHIFT + CMD + R
16.2.0 -> 16.2.1 Upgrade – FreeRadius breaks – breaking Untangle
FreeRadius broke for me, default rules are destroyed during this upgrade. I solved this by upgrading to 16.2.2 by updating the untangle repo to that version and running apt-get update ; apt-get upgrade
.
This was enough to have untangle start back up outside the “normal” upgrade UI process. It was running as expected and was showing the correct version in the UI.
Suricata Looping
Another issue I saw in 16.3.0 -> 16.3.1 was the following message looping in /var/log/uvm/uvm.log
Jul 1 11:07:16 localhost [ExecManagerImpl] INFO ExecManager.exec(systemctl show suricata) = 0 took 9 ms.
Jul 1 11:07:46 localhost [ExecManagerImpl] INFO ExecManager.exec(systemctl show suricata)
Jul 1 11:07:46 localhost [ExecManagerImpl] INFO ExecManager.exec(systemctl show suricata) = 0 took 9 ms.
Jul 1 11:08:16 localhost [ExecManagerImpl] INFO ExecManager.exec(systemctl show suricata)
Jul 1 11:08:16 localhost [ExecManagerImpl] INFO ExecManager.exec(systemctl show suricata) = 0 took 8 ms.
This went on for much longer than it should. I ran systemctl restart untangle-vm
and this got things unwedged and Untangle came back up just fine.
Buster Notes
These are notes – not really instructions. Not liable for terrible things that may happen.
I couldn’t get the uvm to start at all. Found errors in /var/log/uvm/console.log that stated the new uvm was compiled in Java 55 and not Java 52. JDK 11 vs JDK 8.
I ran the following.
apt-get install openjdk-11-jre-headless
update-alternatives --config java
I set the java version to point to the jdk11 that was just installed.