__NOINDEX__
{{Header}}
{{#seo:
|description=How to Upgrade from {{project_name}} 12.x to {{project_name}} 13.x
|image=https://www.whonix.org/w/images/5/5a/Upgrade-1672367640.jpg
}}

= High Level Overview =
1. Backup your data. (Ideally have a copy of your VM, so you can try again.) <br />
2. Consider running the optional [[#Sanity Tests]]. <br />
3. Upgrade {{workstation_product_name}}. <br />
4. Power off {{workstation_product_name}}. <br />
5. Upgrade {{gateway_product_name}}. <br />
6. Restart {{gateway_product_name}}. <br />
7. Restart {{workstation_product_name}} <br />

= Sanity Tests =
<div class="toccolours mw-collapsible mw-collapsed">
These are optional, but recommended. If you want to do them, please press on expand on the right.
<div class="mw-collapsible-content">
<pre>
sudo dpkg --audit ; echo $?
</pre>

Expected output.

<pre>
0
</pre>

<pre>
sudo dpkg --configure -a ; echo $?
</pre>

Expected output:

<pre>
0
</pre>

[[Security_Guide#Updates|Get package upgrades.]]

<pre>
sudo apt-get update
</pre>

<pre>
sudo apt-get dist-upgrade
</pre>

Test wise install python-qt4.

<pre>
sudo apt-get install python-qt4 ; echo $?
</pre>

<pre>
## ... successful installation of python-qt4 ...
0
</pre>
</div>
</div>

= Upgrading =
(Downloading a new {{gateway_product_name}} / {{workstation_product_name}} would be probably easier than applying the following instructions for upgrading, but this upgrade should be quite smooth.)

Backups are important as noted in above chapter [[#Before you start]].

Consider doing the [[#Sanity Tests]] described above. They'll check if your system is affected by obvious grave issues, that you must fix before attempting to upgrade. If your package manager is broken, for example because you mixed packages from Debian stable with packages from Debian testing, then the upgrade may fail in the middle leaving your system in a difficult to resolve situation.

Consider keeping the full terminal (Konsole) log. Even if everything apparently worked, there might be issues after reboot. In case of a bug report in the forums you would be asked to share the upgrading log so the issue can be investigated.

If you are using Qubes R3.0 as your host operating system, you are advised to upgrade your VMs and dom0 to R3.1 before proceeding. Follow the [https://www.qubes-os.org/doc/upgrade-to-r3.1/ Qubes R3.0 > R3.1 upgrade instructions on the Qubes website].

<pre>
sudo whonix_repository --enable --repository stable
</pre>

You are late for upgrading {{project_name}} 12 to {{project_name}} 13. Therefore you need to upgrade {{project_name}} singing key.

Get [[{{project name short}}_Signing_Key|{{project_name}} signing key]].

{{gpg_key_download}}

<pre>
gpg --recv-keys "916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA"
</pre>

Verify [[{{project name short}}_Signing_Key|{{project_name}} signing key]].

Add to apt-key.

<pre>
gpg --export "916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA" | sudo apt-key add -
</pre>

Become root.

<pre>
sudo su
</pre>

Do a usual [[Security_Guide#Updates|upgrade]] of your system's packages from Debian.

Enable extensive debugging so reporting eventual bugs becomes easier.

<pre>
export DEBDEBUG=1
</pre>

{{Update}}

<pre>
apt-get update
</pre>

Upgrade.

<pre>
apt-get dist-upgrade
</pre>


[[Update]] your package lists again. <ref>
This is required because the repository uri of {{project_name}} repository has been upgraded to the new location by the whonix-legacy package.
</ref>

<pre>
apt-get update
</pre>

It is recommended to have the {{gateway_product_name}} or {{workstation_product_name}} meta package installed to make sure nothing is broken. (If you like to uninstall it later as per [[{{project name short}} Debian Packages]], you're free to do so. Still, it is recommended to re-install it before removal to make sure you're as close to official package selection as possible.)

<div class="toccolours mw-collapsible mw-collapsed">
If you are upgrading [[{{q project name short}}|{{q project name}}]], please press on expand on the right.
<div class="mw-collapsible-content">
If you are upgrading {{gateway_product_name}}...

<pre>
apt-get install qubes-whonix-gateway
apt-get purge whonix-gateway
</pre>

If you are upgrading {{workstation_product_name}}...

<pre>
apt-get install qubes-whonix-workstation
apt-get purge whonix-workstation
</pre>
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">
If you are upgrading [[{{non q project name short}}|{{non q project name}}]], please press on expand on the right.
<div class="mw-collapsible-content">
If you are upgrading {{gateway_product_name}}...

<pre>
apt-get install non-qubes-whonix-gateway
apt-get purge whonix-gateway
</pre>

If you are upgrading {{workstation_product_name}}...

<pre>
apt-get install non-qubes-whonix-workstation
apt-get purge whonix-workstation
</pre>
</div>
</div>

Purge packages which are deprecated in {{project_name}} and replaced by new functionality.

<pre>
apt-get purge anon-gw-build-upgrade-tor anon-shared-build-apt-sources-tpo deb.torproject.org-keyring anon-shared-build-upgrade-torsocks timesync
</pre>

Get rid of old packages.

<pre>
apt-get autoremove
</pre>

Delete old problematic files. <ref>
Delete apparmor profile. (timesync has been replaced by sdwdate-gui)

Delete xchat shortcut. (Has been replaced with its successor hexchat.)
</ref>

<pre>
rm -f "/etc/apparmor.d/usr.bin.timesync"
unlink "/home/user/Desktop/xchat.desktop"
unlink "/home/user/Desktop/anondist-torbrowser.desktop"
unlink "/home/user/Desktop/timesync.desktop"
</pre>

If you have been using the apparmor-profiles-extra package (you would know if you did), you should reinstall it.

<pre>
sudo apt-get install --reinstall apparmor-profiles-extra
</pre>

Remember to store the terminal (Konsole) log. (File &rarr; Save Output As)

Reboot required.

<pre>
reboot
</pre>

Qubes users may wish to re-add Tor Browser to Qubes start menu. This can be done the usual Qubes way.

<pre>
Qubes start menu &rarr; domain: anon-whonix &rarr; add more shortcuts &rarr; click Tor Browser (AnonDist) &rarr; press '>' &rarr; OK
</pre>

See also [[#Qubes specific]].

Done.

= Qubes specific =
Optional.

VMs based upon whonix-ws TemplateVM will not inherit the default start menu unless you upgrade the following file. Either apply the following steps or manually add Tor Browser to any new TemplateBasedVM based on whonix-ws TemplateVM. <ref>This is a native Qube - not {{project_name}} - limitation that will not be fixed due to technical difficulties. During VM upgrades, file /var/lib/qubes/vm-templates/whonix-ws/whitelisted-appmenus.list will not be upgraded.</ref>

In dom0. Open /var/lib/qubes/vm-templates/whonix-ws/whitelisted-appmenus.list with root rights.

Add. <ref>https://github.com/adrelanos/qubes-template-whonix/blob/master/appmenus_wheezy_whonix-workstation/vm-whitelisted-appmenus.list</ref>

<pre>
konsole.desktop
dolphin.desktop
nautilus.desktop
whonixcheck.desktop
whonix-irc-chat-support.desktop
janondisttorbrowser.desktop
anondist-torbrowser_update.desktop
</pre>

Save.

Done.

= Footnotes =
{{reflist|close=1}}

[[Category:Documentation]]

{{Footer}}
