Reinstall Qubes-Whonix ™ TemplateVMs: Stable Version
- 1 Introduction
- 2 Reinstall the Whonix TemplateVM
- 3 Optional Steps
- 4 Final Steps
- 5 Footnotes
On occasion it is necessary to reinstall a Whonix TemplateVM from the Qubes repository. 
This chapter 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: To 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 reinstallation guide [archive], however this Whonix ™ wiki entry should be preferred for re-installation of Qubes-Whonix ™. The reason is this guide is Whonix-specific and contains instructions on how to properly configure all settings. 
Use one of the following methods:
- 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 the
--action=upgrade option for reinstalling 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 the NetVM for the UpdateVM. 
Click the Qubes App Launcher (blue/grey "Q") →
Open the Terminal Emulator (Xfce Terminal)
dom0. This step is mandatory. 
Configure salt using Qubes dom0 Community Testing Repository
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 to enable the
qubes-templates-community-testing repository should no longer be required. Please report if these steps were necessary for you.
If you are a interested tester, 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 for you!
In the instructions below, a check is first made for a newer version of the TemplateVM.
- If a newer TemplateVM version exists, install it (
- If no newer TemplateVM version is available, reinstall the existing version (
Unfortunately there is no combined upgrade and reinstall command. 
salt to configure
dom0 settings. 
sudo qubesctl state.sls qvm.anon-whonix
Whonix DisposableVM Template VM
sudo qubesctl state.sls qvm.whonix-ws-dvm
Updates over Tor
To force all TemplateVM updates over Tor,  use salt in
sudo qubesctl state.sls qvm.updates-via-whonix
To undo this setting, modify
dom0.  See also How-to: Fix dom0 Qubes-Whonix ™ UpdatesProxy Settings.
dom0 updates over Tor, set Qubes'
dom0 UpdateVM to
To revert this change, set Qubes'
dom0 UpdateVM to
sys-firewall or another preferred VM. 
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 are 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 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 Qubes-Whonix ™ TemplateVMs is now complete.
- https://qubes-os.org/doc/reinstall-template/ [archive]
This is because the name of the TemplateVMs changed from:
- Technical Introduction: With more technical terms
- Using salt.
qvm-prefs updatevm-name netvm sys-whonix
qvm-prefs updatevm-name netvm sys-whonix
dom0UpdateVM is based on a template that is broken or no longer trusted (the template is broken, misconfigured or compromised), an alternate UpdateVM can be used temporarily. In other words, more specifically, if the Whonix-Gateway ™ TemplateVM (
whonix-gw-15) and/or its Whonix-Gateway ™ ProxyVM (
sys-whonix) are no longer trusted, then configure Qubes
dom0to 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] are 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
qubes-prefs updatevm sys-whonix
To revert this change in
qubes-prefs updatevm sys-firewall
While Debian has enabled AppArmor by default since the
busterrelease, Fedora has not. This matters since Qubes, which is Fedora based, by default uses the
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 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?)