Reinstall Qubes-Whonix ™ TemplateVMs - Stable Version
- 1 Introduction
- 2 Reinstall the Whonix TemplateVM
- 2.1 Qubes Version
- 2.2 UpdateVM Setting
- 2.3 Update dom0
- 2.4 Configure salt using Qubes dom0 Community Testing Repository
- 2.5 Adjust Whonix Version Number
- 2.6 Reinstall
- 2.7 Settings
- 2.8 Optional: Whonix DVM Template VM
- 2.9 Optional: Updates over Tor
- 2.10 Optional: Enable AppArmor
- 2.11 Restart TemplateBasedVMs
- 2.12 Update and Launch Applications
- 2.13 Done
- 3 Footnotes
On occasion it is necessary to reinstall a Whonix TemplateVM from the Qubes repository. 
This usually applies when the template is:
- Outdated: To upgrade to a newer Point Release or testers-only version of Whonix ™.
- Broken: TemplateVMs can become broken and/or unbootable for a number of reasons, like when removing meta-packages that Whonix "depends" on to function properly, or after mixing packages from a later Debian release.
- Misconfigured: Not all TemplateVM modifications are easily reversible. In some cases it may be necessary to reinstall the TemplateVM.
- Compromised: Users may suspect their TemplateVM has been compromised. For further information on this topic, see: Indicators of Compromise
- Testing: Ensure a high quality of future Whonix releases by becoming a Whonix ™ tester.
The obvious reason is any TemplateBasedVMs that are based on the affected TemplateVM will inherit the same issues. Disregarding this advice could lead to serious consequences. For example, a core component of the Whonix security model depends on
sys-whonix forcing all traffic through Tor or blocking it. If
sys-whonix was based on a TemplateVM with a misconfigured or broken firewall, the Whonix security model would be broken. 
Qubes has its own template reinstall guide [archive], however this guide on the Whonix website should be preferred for re-installation of Qubes-Whonix ™, because this guide is Whonix specific and contains instructions how to properly set up all settings. 
You can either:
- A) Uninstall Qubes-Whonix ™ and then Install Qubes-Whonix ™, OR
- B) Follow the Reinstall the Whonix TemplateVM instructions below.
Reinstall the Whonix TemplateVM
Since only Fedora based UpdateVMs support
--action=upgrade option for restalling the TemplateVM, it is recommended to create a dedicated Qubes dom0 UpdateVM based on Qubes Fedora template. Forcing dom0 updates over Tor is still possible by setting
sys-whonix as NetVM for the UpdateVM. 
1. Create a new VM named
2. Configure the NetVM setting of
3. The process of configuring the UpdateVM is now complete.
To launch a dom0 terminal, click the Qubes App Launcher (blue/grey "Q") and then open the Terminal Emulator (Xfce Terminal).
Upgrade Qubes dom0. This step is mandatory. 
Configure salt using Qubes dom0 Community Testing Repository
Testers only. If you are a tester interested, click on Expand on the right.
The following command will configure Qubes dom0 salt to use
qubes-templates-community-testing for downloading Whonix ™. 
sudo qubesctl top.enable qvm.whonix-testing pillar=true
The following steps for enabling
qubes-templates-community-testing repository usually should be no longer required. Please report if these steps were necessary for you
If you are a tester interested, click on Expand on the right.
Adjust Whonix Version Number
This step can be skipped on Qubes
4.0.2 and above when installing Whonix ™ 15.
Please report if this step was necessary or unnecessary for you!
salt for dom0 settings setup. 
sudo qubesctl state.sls qvm.anon-whonix
Optional: Whonix DVM Template VM
In dom0, run.
sudo qubesctl state.sls qvm.whonix-ws-dvm
Optional: Updates over Tor
To force all TemplateVM updates over Tor,  use salt in dom0.
sudo qubesctl state.sls qvm.updates-via-whonix
To force dom0 updates over Tor, set Qubes' dom0 UpdateVM to
To revert this change, set Qubes' dom0 UpdateVM to
sys-firewall or another preferred VM. 
Optional: Enable AppArmor
If you are interested, click on Expand on the right.
The following steps should be completed in dom0 for both
whonix-ws-15 TemplateVMs.  After these settings have been applied to the Whonix templates, the
sys-whonix (ProxyVM) and
anon-whonix (AppVM) will inherit the AppArmor kernel settings.
It is unnecessary to recreate the
anon-whonix TemplateBasedVMs to benefit from the new kernel parameters. It is also important for users to verify AppArmor is active in the
anon-whonix VMs after making these changes.
Any VMs based on the reinstalled TemplateVM must be restarted to reflect the updated file system.
Update and Launch Applications
Before starting applications in the Whonix-Workstation ™ AppVM, update both Whonix-Gateway ™ and Whonix-Workstation ™ TemplateVMs.
To launch an application like Tor Browser:
The process to reinstall Whonix TemplateVMs is now complete. Users should disregard the chapter Manual Reinstallation below.
- https://qubes-os.org/doc/reinstall-template/ [archive]
This is because the name of the TemplateVMs changed from:
- https://whonix.org/Dev/Technical_Introduction#With_more_technical_terms [archive]
- Using salt.
qvm-prefs updatevm-name netvm sys-whonix
qvm-prefs updatevm-name netvm sys-whonix
If the dom0 UpdateVM is based on a template that is broken or no longer trusted, ref Template is broken, misconfigured or compromised ref an alternate UpdateVM can be used temporarily. In other words, more specifically, if the user no longer trusts its Whonix-Gateway ™ TemplateVM (
whonix-gw-15) and/or its Whonix-Gateway ™ ProxyVM (
sys-whonix), then configure Qubes dom0 to use a different UpdateVM by applying the following steps. TODO
- This is required to make sure a recent version of Qubes repository definition files, Qubes salt, qubes-core-admin-addon-whonix [archive] as well as qubes-mgmt-salt-dom0-virtual-machines [archive] gets installed.
- Which is invoked by
- Note the file extension
- qubes-dom0-update combined --action=upgrade --action=reinstall command [archive]
- phase out manual use of qubes-dom0-update by user / replace it by salt [archive]
- https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/whonix-ws-15-dvm.sls [archive]
- In Qubes-R4 and above, RPC/qrexec UpdatesProxy is used to update TemplateVMs
- salt [archive]
- https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/updates-via-whonix.sls [archive]
- https://groups.google.com/forum/?_escaped_fragment_=topic/qubes-users/_jI2uWPPMMA#!topic/qubes-users/_jI2uWPPMMA [archive]
Or manually set the torified UpdateVM in dom0 terminal.
qubes-prefs updatevm sys-whonix
To revert this change in dom0 terminal, run.
qubes-prefs updatevm sys-firewall
While Debian enabled AppArmor by default since Debian
buster, Fedora does not. This matters since Qubes, which is Fedora based, by default uses dom0, not VM kernel. Therefore this is still required even though Whonix is based on a recent enough Debian version.
- Since Qubes R3.0, TemplateBasedVMs inherit the kernelopts setting of their TemplateVM [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 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?)