Reinstall Qubes-Whonix ™ TemplateVMs: Stable Version
From Whonix
< Qubes
Introduction[edit]
On occasion it is necessary to reinstall a Whonix TemplateVM from the Qubes repository. [1]
Note: If Qubes-Whonix ™ 14 is installed and you want to get Qubes-Whonix ™ 15, there is no need to follow the instructions on this page. Refer to the Install Qubes-Whonix ™ guide instead because it is easier. [2]
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.
Warning[edit]
If the Whonix ™ TemplateVM is broken, misconfigured or potentially compromised, discontinue using any VMs based on the affected template.
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. [3]
Reinstallation Methods[edit]
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. [4]
Note: The root file system of the affected TemplateVM will be lost during the reinstallation process. It is recommended to create a backup of any important files first.
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[edit]
Qubes Version[edit]
UpdateVM Setting[edit]
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. [5]
1. Create a new VM named dom0-updatevm
.
Qubes VM Manager
→ VM
→ Create AppVM
- Name and label: Name the AppVM. Do not include any personal information (if the AppVM is compromised, the attacker could run
qubesdb-read /name
to reveal the VM name). Name the AppVM something generic, for example:dom0-updatevm
. - Color: Choose a color label for the UpdateVM.
- Use this template: Choose the Fedora-based TemplateVM. For example:
fedora-32
. - Standalone: Leave the Standalone field unchecked.
- Type: Choose the type
AppVM
. - Allow networking: Choose the desired NetVM from the list. For example:
sys-whonix
. - Press:
OK
.
2. Configure the NetVM setting of dom0-updatevm
.
- Option A: If non-torified, clearnet Qubes
dom0
updates are preferred, set the NetVM ofdom0-updatevm
for example tosys-firewall
.
Qube Manager
→ dom0-updatevm
→ Qube settings
→ Networking: sys-firewall
→ OK
[6]
- Option B: If torified Qubes
dom0
updates are preferred, set the NetVM ofdom0-updatevm
to Whonix-Gateway ™.
Qube Manager
→ dom0-updatevm
→ Qube settings
→ Networking: sys-whonix
→ OK
[7]
3. The process of configuring the UpdateVM is now complete.
Update dom0[edit]
Launch a dom0
terminal.
Click the Qubes App Launcher (blue/grey "Q")
→ Open the Terminal Emulator (Xfce Terminal)
Upgrade Qubes dom0
. This step is mandatory. [9]
sudo qubes-dom0-update
Configure salt using Qubes dom0 Community Testing Repository[edit]
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 ™. [10]
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.
1. Enable qubes-templates-community-testing
repository.
View the Qubes Templates .repo
[archive] file.
cat /etc/yum.repos.d/qubes-templates.repo
2. Ensure the file contains [qubes-templates-community-testing]
.
The following text should be included.
[qubes-templates-community-testing] name = Qubes Community Templates repository #baseurl = https://yum.qubes-os.org/r$releasever/templates-community-testing metalink = https://yum.qubes-os.org/r$releasever/templates-community-testing/repodata/repomd.xml.metalink enabled = 0 fastestmirror = 1 gpgcheck = 1 gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-$releasever-templates-community
3. Fix any missing sections.
If the [qubes-templates-community-testing]
section is missing, then the user has probably already modified the file. In this case dnf
[11] preserves user changes by saving updates to /etc/yum.repos.d/qubes-templates.repo.rpmnew
[12] instead of overwriting the file. Since the .repo.rpmnew
file is ignored by qubes-dom0-update
, the .repo
file must be manually updated.
Either:
- Manually add the changes from
.repo.rpmnew
to the.repo
file; or - Overwrite the
.repo
file with the.repo.rpmnew
file:-
sudo cp /etc/yum.repos.d/qubes-templates.repo.rpmnew /etc/yum.repos.d/qubes-templates.repo
- And then manually add back necessary changes. If the command fails because
/etc/yum.repos.d/qubes-templates.repo.rpmnew
does not exist, then the user probably has[qubes-templates-community-testing]
already.
-
Adjust Whonix Version Number[edit]
This step can be skipped on Qubes 4.0.2
and above when installing Whonix ™ 15.
1. In dom0
open file whonix.jinja
with root rights. [13]
sudo nano /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
2. Change 14
to 15
.
3. Save the file.
Please report if this step was necessary for you!
Reinstall[edit]
In the instructions below, a check is first made for a newer version of the TemplateVM.
- If a newer TemplateVM version exists, install it (
--action=upgrade
). - If no newer TemplateVM version is available, reinstall the existing version (
--action=reinstall
).
Unfortunately there is no combined upgrade and reinstall command. [14]
1. Launch a dom0
terminal.
Click the Qubes App Launcher (blue/grey "Q")
→ Open the Terminal Emulator (Xfce Terminal)
2. First try upgrading the TemplateVM.
This will only work if there is a new Point Release of the TemplateVM.
Execute the following command. Replace qubes-template-package
with either: qubes-template-whonix-ws-15
or qubes-template-whonix-gw-15
, respectively.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade <qubes-template-package>
For example, to reinstall and upgrade whonix-gw-15
TemplateVM.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-gw-15
For example, to reinstall and upgrade whonix-ws-15
TemplateVM.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-ws-15
3. Read the output of the above command. The following outcomes are possible, either:
- A) The TemplateVM is upgraded. In that case, skip step four below ("Reinstall the TemplateVM"); OR
- B) The commands above might finish relatively quickly and state
No new updates available
. In that case, proceed with step four below ("Reinstall the TemplateVM"); OR - C) A TemplateVM upgrade is unsupported. This might happen if a non-Fedora based UpdateVM is used in conjunction with the
--action=upgrade
option. See: UpdateVM Setting for further information; OR - D) An error has occurred, such as a networking issue.
4. Optional: Reinstall the TemplateVM.
If --action=upgrade
at step two did not actually reinstall the TemplateVM, this means there is no new Point Release available at present. This also means the TemplateVM has not been actually reinstalled and further action is required (see below).
If unsure, the commands below are safe in any case because if you already have the latest TemplateVM version, then it will simply be reinstalled again.
Execute the following command. Replace qubes-template-package
with either: qubes-template-whonix-ws-15
or qubes-template-whonix-gw-15
, respectively.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall <qubes-template-package>
For example, to reinstall whonix-gw-15
TemplateVM.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-gw-15
For example, to reinstall whonix-ws-15
TemplateVM.
sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws-15
Read the output of the above command. There are two possible outcomes, either:
- A) The TemplateVM was reinstalled; OR
- B) An error has occurred, such as a networking issue.
Settings[edit]
This step is mandatory. [15]
Use salt
to configure dom0
settings. [16]
sudo qubesctl state.sls qvm.anon-whonix
Optional Steps[edit]
Whonix DisposableVM Template VM[edit]
In Qubes R4 and above a whonix-ws-15-dvm
DisposableVM Template can optionally be set up as a base for Disposable VMs. [17]
In dom0
, run.
sudo qubesctl state.sls qvm.whonix-ws-dvm
Updates over Tor[edit]
TemplateVMs[edit]
To force all TemplateVM updates over Tor, [18] use salt in dom0
.
sudo qubesctl state.sls qvm.updates-via-whonix
To undo this setting, modify /etc/qubes-rpc/policy/qubes.UpdatesProxy
in dom0
. [19] See also How-to: Fix dom0 Qubes-Whonix ™ UpdatesProxy Settings.
dom0[edit]
To force dom0
updates over Tor, set Qubes' dom0
UpdateVM to sys-whonix
. [20]
Qube Manager
→ System
→ Global Settings
→ Dom0 UpdateVM:
sys-whonix
→ OK
To revert this change, set Qubes' dom0
UpdateVM to sys-firewall
or another preferred VM. [21]
Qubes Manager
→ System
→ Global Settings
→ Dom0 UpdateVM:
sys-firewall
→ OK
Enable AppArmor[edit]
If you are interested, click on Expand on the right.
The following steps should be completed in dom0
for both whonix-gw-15
and whonix-ws-15
TemplateVMs. [22] 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 sys-whonix
and anon-whonix
TemplateBasedVMs to benefit from the new kernel parameters.[23] It is also important to verify AppArmor is active in the sys-whonix
and anon-whonix
VMs after making these changes.
Whonix-Gateway ™[edit]
1. Open a dom0
terminal.
Qubes App Launcher (blue/grey "Q")
→ System Tools
→ Xfce Terminal
2. List the current kernel parameters.
qvm-prefs -g whonix-gw-15 kernelopts
Qubes R4 and later releases will show.
nopat
3. Keep the existing kernel parameters and add apparmor=1 security=apparmor
.
For example.
qvm-prefs -s whonix-gw-15 kernelopts "nopat apparmor=1 security=apparmor"
qvm-prefs -s sys-whonix kernelopts "nopat apparmor=1 security=apparmor"
4. List the current kernel parameters again (hit the up arrow key twice; it is unnecessary to type the command again).
qvm-prefs -g whonix-gw-15 kernelopts
The output should show AppArmor is part of the new kernel parameters. For example.
nopat apparmor=1 security=apparmor
5. Start the sys-whonix
ProxyVM and confirm AppArmor is now active.
sudo aa-status --enabled ; echo $?
The output should show.
0
Whonix-Workstation ™[edit]
1. Open a dom0
terminal.
Qubes App Launcher (blue/grey "Q")
→ System Tools
→ Xfce Terminal
2. List the current kernel parameters.
qvm-prefs -g whonix-ws-15 kernelopts
Qubes R4 and later releases will show.
nopat
3. Keep the existing kernel parameters and add apparmor=1 security=apparmor
.
For example.
qvm-prefs -s whonix-ws-15 kernelopts "nopat apparmor=1 security=apparmor"
qvm-prefs -s anon-whonix kernelopts "nopat apparmor=1 security=apparmor"
4. List the current kernel parameters again (hit the up arrow key twice; it is unnecessary to type the command again).
qvm-prefs -g whonix-ws-15 kernelopts
The output should show AppArmor is part of the new kernel parameters. For example.
nopat apparmor=1 security=apparmor
5. Start the anon-whonix
AppVM and confirm AppArmor is now active.
sudo aa-status --enabled ; echo $?
The output should show.
0
Final Steps[edit]
Restart TemplateBasedVMs[edit]
Any VMs based on the reinstalled TemplateVM must be restarted to reflect the updated file system.
Update and Launch Applications[edit]
Before starting applications in the Whonix-Workstation ™ AppVM, update both Whonix-Gateway ™ and Whonix-Workstation ™ TemplateVMs.
To launch an application like Tor Browser:
Qubes App Launcher (blue/grey "Q")
→ Domain: anon-whonix
→ Tor Browser (AnonDist)
Done[edit]
The process to reinstall Qubes-Whonix ™ TemplateVMs is now complete.
Footnotes[edit]
- ↑ https://qubes-os.org/doc/reinstall-template/ [archive]
- ↑
This is because the name of the TemplateVMs changed from:
whonix-gw-14
towhonix-gw-15
whonix-ws-14
towhonix-ws-15
- ↑ Technical Introduction: With more technical terms
- ↑ Using salt.
- ↑
sys-net
→sys-firewall
→sys-whonix
→UpdateVM
UpdateVM
→sys-whonix
→sys-firewall
→sys-net
- ↑
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 (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 Qubesdom0
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] are installed.
- ↑
- ↑ Which is invoked by
qubes-dom0-update
. - ↑ Note the file extension
.repo.rpmnew
. - ↑
- ↑ 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]
- ↑ Dev/Qubes#salt
- ↑ 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
- doc/software-update-vm/#technical-details-r40
- 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 has enabled AppArmor by default since the
buster
release, Fedora has not. This matters since Qubes, which is Fedora based, by default uses thedom0
(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].
Whonix ™ is Supported by Evolution Host DDoS Protected VPS. Stay private and get your VPS with Bitcoin or Monero.
Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki
Did you know that Whonix ™ could provide protection against backdoors? See Verifiable Builds. Help is wanted and welcomed.
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.