DO NOT USE YET! This page is only for preparation / notes for now. Whonix ™ 16 does not exist yet at all

TODO: remove NOINDEX of this page

Notices[edit]

Table: Upgrading Whonix Notices

Notice	Description
Difficulty	Downloading a new Whonix-Gateway ™ / Whonix-Workstation ™ is easier than applying the Release Upgrade instructions on this page, but this process is relatively smooth.
Release Upgrade vs Download	To use Whonix ™ 15, users can either: A) Release upgrade existing Whonix ™ 14 images using the instructions on this page; or B) Re-install Whonix ™ by downloading the new release, which is much simpler than upgrading Non-Qubes-Whonix ™ 15: download the new release. Qubes-Whonix ™ 15: download the new release.
Standard Upgrades	For standard ("everyday") upgrade instructions see Operating System Software and Updates. The instructions on this page describe how to perform a Release Upgrade from Whonix ™ 14 to Whonix ™ 15.
Qubes EOL	Qubes R4 and above only -- Qubes OS 3.2 has reached End Of Life ^[archive]. If you are using Qubes R3.2 / R3.2.1, Qubes-Whonix ™ upgrades are unsupported.

High Level Overview[edit]

Backup all data - ideally have a copy of the VM(s) so it is possible to try again (if necessary).
Perform the usual standard ("everyday") upgrade instructions.
Consider running the optional sanity tests.
Release Upgrade Whonix-Workstation ™ (whonix-ws-14).
Power off Whonix-Workstation ™ (whonix-ws-14).
Release Upgrade Whonix-Gateway ™ (whonix-gw-14).
Restart Whonix-Gateway ™ (whonix-gw-14).
Restart Whonix-Workstation ™ (whonix-ws-14).

Sanity Tests[edit]

These are optional, but recommended. To complete sanity tests, please press on expand on the right.

sudo dpkg --audit ; echo $?

sudo dpkg --audit ; echo $?

Expected output.

0

sudo dpkg --configure -a ; echo $?

sudo dpkg --configure -a ; echo $?

Expected output.

0

Get package upgrades.

sudo apt-get update

sudo apt-get update

sudo apt-get dist-upgrade

sudo apt-get dist-upgrade

For testing purposes, install python-qt4.

sudo apt-get install python-qt4 ; echo $?

sudo apt-get install python-qt4 ; echo $?

## ... successful installation of python-qt4 ...
0

## ... successful installation of python-qt4 ...
0

Upgrading[edit]

Introduction[edit]

First consider completing the sanity tests described above; the system is checked for obvious and grave issues that must be fixed before attempting an upgrade. For example, if the package manager is broken due to the mixing of packages from both Debian stable and Debian testing, then the upgrade may fail part way through, leaving the system in an unstable state that is difficult to resolve.

Consider retaining the full terminal log. Even if the upgrade appears successful, there might be issues following reboot. To properly report a bug in the Whonix ™ forums it is necessary to share the upgrade log so the issue can be investigated.

KDE vs XFCE note: Whonix ™ KDE has been deprecated ^[archive], meaning Whonix ™ KDE is unsupported from Whonix ™ 15 -- all users should upgrade to Whonix ™ XFCE. These upgrade instructions replace the KDE desktop environment ^[1] and default applications ^[2] with those associated with XFCE.

Update Package and Sources Lists[edit]

First upgrade the system's packages by performing the Standard Upgrade Steps.

All Platforms[edit]

Update Whonix ™ apt sources list.

sudo whonix_repository --enable --codename bullseye

sudo whonix_repository --enable --codename bullseye

Update Debian apt sources list.

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/debian.list

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/debian.list

Delete the backports, testing and unstable repositories, as well as the default release APT config snippet. ^[3]

sudo rm -f /etc/apt/sources.list.d/backports.list /etc/apt/sources.list.d/testing.list /etc/apt/sources.list.d/unstable.list /etc/apt/apt.conf.d/70defaultrelease

sudo rm -f /etc/apt/sources.list.d/backports.list /etc/apt/sources.list.d/testing.list /etc/apt/sources.list.d/unstable.list /etc/apt/apt.conf.d/70defaultrelease

Qubes-Whonix ™ Only[edit]

Update Qubes' apt sources list.

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/qubes*.list

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/qubes*.list

Preparation[edit]

Become root.

sudo su

sudo su

Enable extensive debugging so the reporting of any eventual bugs is easier.

export DEBDEBUG=1

export DEBDEBUG=1

Update the package lists.

apt-get update

apt-get update

Upgrade[edit]

Distribution Upgrade[edit]

To perform a distribution upgrade, it is recommended to run the following command which uses apt-get-noninteractive ^[archive]; see the footnotes for technical reasons. ^[4] ^[5] ^[6]

Ignore any eventual errors relating to exim* and/or mailx - these packages will be removed in the next step.

apt-get-noninteractive dist-upgrade --no-install-recommends

apt-get-noninteractive dist-upgrade --no-install-recommends

Purge packages which are not required and broken. On some platforms these packages are not installed, but the step is completely harmless.

apt-get purge exim*

apt-get purge exim*

Restart Necessary Services[edit]

Restart whonix-legacy service. ^[7]

service whonix-legacy restart

service whonix-legacy restart

Metapackage Installation[edit]

Note: It is possible that the following packages are already installed, but these steps are necessary to confirm it.

Non-Qubes-Whonix[edit]

In Whonix-Gateway ™, install package non-qubes-whonix-gateway-xfce.
```
apt-get install non-qubes-whonix-gateway-xfce
```
apt-get install non-qubes-whonix-gateway-xfce
In Whonix-Workstation ™, install package non-qubes-whonix-workstation-xfce.
```
apt-get install non-qubes-whonix-workstation-xfce
```
apt-get install non-qubes-whonix-workstation-xfce

Qubes-Whonix[edit]

In Whonix-Gateway ™ (whonix-gw-14), install package qubes-whonix-gateway.
```
apt-get install qubes-whonix-gateway
```
apt-get install qubes-whonix-gateway
In Whonix-Workstation ™ (whonix-ws-14), install package qubes-whonix-workstation.
```
apt-get install qubes-whonix-workstation
```
apt-get install qubes-whonix-workstation

Remove Unneeded Packages[edit]

Note: This step is not required for Non-Qubes-Whonix ™ XFCE users.

This long command will remove deprecated meta packages and KDE leftovers; simply cut and paste the entire command. ^[8] ^[9]

Run the following command in both Whonix-Gateway ™ and Whonix-Workstation ™.

TODO: none yet

apt-get purge --yes TODO ; \

apt-get purge --yes TODO ; \

Autoremove[edit]

Remove packages which are no longer required.

apt-get autoremove

apt-get autoremove

Revert to Regular Privileges[edit]

If you are root already (previously became root using sudo su), then exit now.

Open a terminal and run.

exit

exit

Whonix ™ XFCE Desktop Config[edit]

Qubes-Whonix ™ users: Please skip this step. ^[10]

Non-Qubes-Whonix ™ users: Please click on expand on the right.

Create folder /home/user/desktop-backup

mkdir -p /home/user/desktop-backup

mkdir -p /home/user/desktop-backup

Reset the XFCE desktop configuration.

mv /home/user/.config/xfce4 /home/user/desktop-backup/

mv /home/user/.config/xfce4 /home/user/desktop-backup/

Delete the first-boot-skel.done file. ^[11]

sudo rm -f /var/cache/anon-base-files/first-boot-skel.done

sudo rm -f /var/cache/anon-base-files/first-boot-skel.done

Execute /usr/lib/anon-base-files/first-boot-skel ^[archive] to get Whonix ™ XFCE Desktop Config ^[archive].

sudo /usr/lib/helper-scripts/first-boot-skel

sudo /usr/lib/helper-scripts/first-boot-skel

Terminal Log[edit]

Remember to retain the terminal log:

Edit → Select All → Edit → Copy → Open Editor → Paste → Save

APT Sources Lists[edit]

Open a new terminal window. ^[12]

Run Whonix ™ APT Repository Tool. ^[13]

lxsudo whonix-repository-wizard

lxsudo whonix-repository-wizard

As explained in step Distribution Upgrade, all system configuration files in /etc were reset to the distributor default. If modifications were previously made to any files in folder /etc/apt/sources.list.d, they should be re-added at this step (if desired).

Review all files in folder /etc/apt/sources.list.d

lxsudo mousepad /etc/apt/sources.list.d/*

lxsudo mousepad /etc/apt/sources.list.d/*

If changes were made, follow the standard ("everyday") upgrade instructions.

Reboot[edit]

A reboot is required.

sudo reboot

sudo reboot

Start Menu[edit]

Non-Qubes-Whonix ™ users: Please skip this step.

Qubes-Whonix ™ users: Please click on expand on the right.

The upgrade process does not upgrade the Qubes appmenus (start menu) entries and these must be manually updated. The reason is many applications that were installed by default in Qubes-Whonix ™ 14 are no longer present in Qubes-Whonix ™ 15, due to the change from KDEish to XFCEish default applications. ^[14]

Qubes appmenu → anon-whonix → Add more shortcuts
Qubes appmenu → sys-whonix → Add more shortcuts
Qubes appmenu → whonix-gw-14 → Add more shortcuts
Qubes appmenu → whonix-ws-14 → Add more shortcuts

Done[edit]

All necessary steps are now complete.

As a final recommendation, it is advisable to run whonixcheck to check numerous, important system variables. ^[15]

Automated[edit]

Testers only! Non-Qubes-Whonix only. XFCE only. Professional Support only.

This would probably brick Qubes-Whonix!

Create a file /usr/lib/release-upgrade with root rights.

lxsudo mousepad /usr/lib/release-upgrade

Paste the following contents. ^[16]

#!/bin/bash

## Copyright (C) 2020 - 2020 ENCRYPTED SUPPORT LP <adrelanos@whonix.org>
## See the file COPYING for copying conditions.

set -x
set -e
set -o pipefail

error_handler() {
   local MSG="\
###########################################################
## Something went wrong. Please report this bug!
##
## BASH_COMMAND: $BASH_COMMAND
###########################################################\
"
   echo "$MSG"
   exit 1
}

trap "error_handler" ERR

if [ "$(id -u)" != "0" ]; then
   true "ERROR: Must run as root."
   true "sudo $0"
   exit 112
fi

if test -e /usr/share/anon-gw-base-files/gateway ; then
   pkg="non-qubes-whonix-gateway-xfce"
elif test -e /usr/share/anon-ws-base-files/workstation ; then
   pkg="non-qubes-whonix-workstation-xfce"
else
   error "Could not detect gateway or workstation"
fi

export DEBDEBUG=1

dpkg --audit

dpkg --configure -a

rm -f /etc/apt/sources.list.d/whonix.list

sed -i 's/timeout_after="240"/timeout_after="600"/g' /usr/lib/security-misc/apt-get-update

sed -i 's/update \&/update "$@" \&/g' /usr/lib/security-misc/apt-get-update

/usr/lib/security-misc/apt-get-update -o Acquire::Languages=none -o Acquire::IndexTargets::deb::Contents-deb::DefaultEnabled=false

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive --yes --no-install-recommends dist-upgrade

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive --yes --no-install-recommends install python-qt4

dpkg --audit

dpkg --configure -a

whonix_repository --enable --codename bullseye

sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/debian.list

rm -f /etc/apt/sources.list.d/backports.list /etc/apt/sources.list.d/testing.list /etc/apt/sources.list.d/unstable.list /etc/apt/apt.conf.d/70defaultrelease

sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/qubes*.list &>/dev/null || true

/usr/lib/security-misc/apt-get-update -o Acquire::Languages=none -o Acquire::IndexTargets::deb::Contents-deb::DefaultEnabled=false

apt-get-noninteractive dist-upgrade --yes --no-install-recommends

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes purge exim* || true

service whonix-legacy restart

apt-get-noninteractive --yes --no-install-recommends install "$pkg"

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive purge --yes non-qubes-whonix-gateway || true
apt-get-noninteractive purge --yes non-qubes-whonix-gateway-kde || true
apt-get-noninteractive purge --yes non-qubes-whonix-workstation || true
apt-get-noninteractive purge --yes non-qubes-whonix-workstation-kde || true
apt-get-noninteractive purge --yes whonix-gw-kde-desktop-conf || true
apt-get-noninteractive purge --yes whonix-gw-desktop-shortcuts || true
apt-get-noninteractive purge --yes hardened-desktop-applications-kde || true
apt-get-noninteractive purge --yes hardened-desktop-environment-essential-kde || true
apt-get-noninteractive purge --yes sddm || true
apt-get-noninteractive purge --yes kde-* || true
apt-get-noninteractive purge --yes libkde* || true
apt-get-noninteractive purge --yes qml-module-org-kde-* || true
apt-get-noninteractive purge --yes polkit-kde-agent-1 || true
apt-get-noninteractive purge --yes kded5 || true
apt-get-noninteractive purge --yes *kdelibs* || true
apt-get-noninteractive purge --yes kdesudo || true
apt-get-noninteractive purge --yes ark || true
apt-get-noninteractive purge --yes konsole || true
apt-get-noninteractive purge --yes apt-cacher-ng || true
apt-get-noninteractive purge --yes wpasupplicant || true

if test -e /usr/share/anon-gw-base-files/gateway ; then
   apt-get-noninteractive purge --yes vlc* || true
   apt-get-noninteractive purge --yes libvlc* || true
   apt-get-noninteractive purge --yes phonon* || true
fi

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes autoremove

dpkg --audit

dpkg --configure -a

sudo -u user mkdir -p /home/user/desktop-backup || true
sudo -u user mv /home/user/Desktop/*.desktop /home/user/desktop-backup/ || true
sudo -u user mv /home/user/.config/xfce4 /home/user/desktop-backup/ || true

rm -f /var/cache/anon-base-files/first-boot-skel.done || true
/usr/lib/helper-scripts/first-boot-skel || true

unlink /usr/local/etc/onion-grater-merger.d/* || true

rm -f /usr/local/etc/onion-grater-merger.d/40_bisq.yml

sudo sed -i "s#/usr/sbin/tinyproxy#/usr/bin/tinyproxy#g" /lib/systemd/system/qubes-updates-proxy.service &>/dev/null || true

true "OK. Success."

Safe.

Make executable.

sudo chmod +x /usr/lib/release-upgrade

Run release upgrade script.

sudo /usr/lib/release-upgrade

If everything went well, at the end it will show OK. Success..

Footnotes[edit]

↑ Non-Qubes-Whonix only since Qubes-Whonix ™ does not have a desktop environment installed - that is dependent on dom0.
↑ Users have the freedom to retain KDE applications and/or to reinstall those after the upgrade.
↑ This step is only required if they were previously enabled, but the command is harmless either way.
↑ apt-get-noninteractive prevents the user from being asked difficult technical questions anytime during the upgrade, since the upgrade is stopped until the question is answered. apt-get-noninteractive uses apt-get with -o Dpkg::Options::=--force-confnew. This means apt-get will prefer config files shipped by the distribution in case there is an existing modified config file on the system. Old config files should be automatically moved to configfile.dpkg-old.
↑ Advanced users can use apt-get rather than apt-get-noninteractive. However, it is probably best to use apt-get-noninteractive and to re-apply custom configurations after the upgrade.
↑ Parameter --no-install-recommends prevents the installation of packages (from debian/control Recommends: packages by Debian) which are not useful, confusing or waste disk space inside of virtual machines, such as xscreensaver. For other reasons why Whonix ™ uses --no-install-recommends, see: Technical Stuff.
↑ A manual restart is required because apt-get-noninteractive is being used. This step is not crucial since it would also run after reboot.
↑ In order to separately run the commands, it is necessary to remove the ; and \ characters at the end.
↑ Unfortunately, as of Debian buster apt-get no longer allows a single apt-get purge command followed by a list of all packages. If one of the packages is not already installed, then it aborts the whole command and also refuses to uninstall those which are still present. Therefore, to run commands in succession the ; parameter is used, while \ allows a single long command to be split into multiple lines for better readability.
↑ VM XFCE is not being used in Qubes and package Whonix ™ XFCE Desktop Config ^[archive] is also not installed, so this step is unnecessary. If you want to apply this anyhow, it should be done in every AppVM.
↑ So it can be re-run.
↑ Because GUI application whonix-repository-wizard should not be run as root.
↑ To select the correct APT repository for use.
↑ https://groups.google.com/d/topic/qubes-devel/pkvvm1WNznY ^[archive]

↑ The following message is not a concern.

The following packages were automatically installed and are no longer required:
  hardened-packages-recommended-cli non-qubes-vm-enhancements-gui whonix-workstation-default-applications-gui whonix-ws-desktop-shortcuts

↑
- https://github.com/Whonix/whonix-legacy/blob/master/usr/lib/release-upgrade ^[archive]
- https://raw.githubusercontent.com/Whonix/whonix-legacy/master/usr/lib/release-upgrade ^[archive]

Whonix ™ is Supported by Evolution Host DDoS Protected VPS. Stay private and get your VPS with Bitcoin or Monero.

Jobs in USA

Follow:

Donate:

Share: Twitter | Facebook

Want to make Whonix safer and more usable? We're looking for helping hands. Check out the Open Issues ^[archive] and development forum ^[archive].

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee ^[archive] of the Open Invention Network ^[archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian ^[archive]. Debian is a registered trademark ^[archive] owned by Software in the Public Interest, Inc ^[archive].

Whonix ™ is produced independently from the Tor® ^[archive] anonymity software and carries no guarantee from The Tor Project ^[archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.

[1] Non-Qubes-Whonix only since Qubes-Whonix ™ does not have a desktop environment installed - that is dependent on dom0.

[2] Users have the freedom to retain KDE applications and/or to reinstall those after the upgrade.

[3] This step is only required if they were previously enabled, but the command is harmless either way.

[4] apt-get-noninteractive prevents the user from being asked difficult technical questions anytime during the upgrade, since the upgrade is stopped until the question is answered. apt-get-noninteractive uses apt-get with -o Dpkg::Options::=--force-confnew. This means apt-get will prefer config files shipped by the distribution in case there is an existing modified config file on the system. Old config files should be automatically moved to configfile.dpkg-old.

[5] Advanced users can use apt-get rather than apt-get-noninteractive. However, it is probably best to use apt-get-noninteractive and to re-apply custom configurations after the upgrade.

[6] Parameter --no-install-recommends prevents the installation of packages (from debian/control Recommends: packages by Debian) which are not useful, confusing or waste disk space inside of virtual machines, such as xscreensaver. For other reasons why Whonix ™ uses --no-install-recommends, see: Technical Stuff.

[7] A manual restart is required because apt-get-noninteractive is being used. This step is not crucial since it would also run after reboot.

[8] In order to separately run the commands, it is necessary to remove the ; and \ characters at the end.

[9] Unfortunately, as of Debian buster apt-get no longer allows a single apt-get purge command followed by a list of all packages. If one of the packages is not already installed, then it aborts the whole command and also refuses to uninstall those which are still present. Therefore, to run commands in succession the ; parameter is used, while \ allows a single long command to be split into multiple lines for better readability.

[10] VM XFCE is not being used in Qubes and package Whonix ™ XFCE Desktop Config ^[archive] is also not installed, so this step is unnecessary. If you want to apply this anyhow, it should be done in every AppVM.

[11] So it can be re-run.

[12] Because GUI application whonix-repository-wizard should not be run as root.

[13] To select the correct APT repository for use.

[14] ttps://groups.google.com/d/topic/qubes-devel/pkvvm1WNznY ^[archive]

[15] The following message is not a concern.
The following packages were automatically installed and are no longer required: hardened-packages-recommended-cli non-qubes-vm-enhancements-gui whonix-workstation-default-applications-gui whonix-ws-desktop-shortcuts

[16] 
https://github.com/Whonix/whonix-legacy/blob/master/usr/lib/release-upgrade ^[archive]

https://raw.githubusercontent.com/Whonix/whonix-legacy/master/usr/lib/release-upgrade ^[archive]

[17] ttps://github.com/Whonix/whonix-legacy/blob/master/usr/lib/release-upgrade ^[archive]

[18] ttps://raw.githubusercontent.com/Whonix/whonix-legacy/master/usr/lib/release-upgrade ^[archive]

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]

[16]

Upgrading Whonix 15 to Whonix 16

From Whonix

Contents