Reinstall Qubes-Whonix™ Templates
How to Reinstall Qubes-Whonix Templates
Introduction[edit]
On occasion it is necessary to reinstall a Whonix template from the Qubes repository. [1]
This chapter usually applies when the template is:
- Outdated: To upgrade to a newer Point Release or testers-only version of Whonix.
- Broken: Templates 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 Template modifications are easily reversible. In some cases it may be necessary to reinstall the Template.
- Compromised: Users may suspect their Template 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]
The obvious reason is any App Qubes that are based on the affected Template 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 Template with a misconfigured or broken firewall, the Whonix security model would be broken. [3]
Reinstallation Methods[edit]
Qubes has its own template reinstallation guide, 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]
Use one of the following methods:
- A) Uninstall Qubes-Whonix and then Install Qubes-Whonix; OR
- B) Follow the Reinstall the Whonix template instructions below.
Reinstall the Whonix template[edit]
UpdateVM Setting[edit]
Since only Fedora-based UpdateVMs support the --action=upgrade
option for reinstalling the Template, 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 App Qube
- Name and label: Name the App Qube. Do not include any personal information (if the App Qube is compromised, the attacker could run
qubesdb-read /name
to reveal the VM name). Name the App Qube something generic, for example:dom0-updatevm
. - Color: Choose a color label for the UpdateVM.
- Use this template: Choose the Fedora-based Template. For example:
fedora-34
. (There may or may not be a higher version number than34
than there was at time of writing.) - Standalone: Leave the Standalone field unchecked.
- Type: Choose the type
App Qube
. - 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]
1. Launch a dom0
terminal.
Click the Qubes App Launcher (blue/grey "Q")
→ Open the Terminal Emulator (Xfce Terminal)
2. Upgrade Qubes dom0
.
This step is mandatory. [9] [10]
sudo qubes-dom0-update --show-output --console
3. Done.
dom0 upgrade has been completed.
Configure salt using Qubes dom0 Community Testing Repository[edit]
Optional.
If you are an interested tester, click on Expand on the right.
The following command will configure Qubes dom0
salt to use qubes-templates-community-testing
for downloading Whonix. [11]
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 an interested tester, click on Expand on the right.
1. Enable qubes-templates-community-testing
repository.
View the Qubes Templates .repo
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
[12] preserves user changes by saving updates to /etc/yum.repos.d/qubes-templates.repo.rpmnew
[13] 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]
1. Introduction.
If the previous sudo qubes-dom0-update
was completed, it should not be necessary to verify the version number. However, this is mentioned because many users fail to update dom0
packages beforehand.
2. View local salt Whonix version number.
In dom0
.
View contents of file /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
.
sudo cat /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
3. Example output.
4. Interpretation.
Verify whonix_version
is 17
.
If it shows something else, then Qubes dom0
is outdated. In that case, it is not possible to continue. [14] [15] [16]
5. Done.
Version number verification has been completed.
Reinstall[edit]
In the instructions below, a check is first made for a newer version of the Template.
- If a newer Template version exists, install it (
upgrade
). - If no newer Template version is available, reinstall the existing version (
reinstall
).
Unfortunately there is no combined upgrade and reinstall command. [17]
1. Launch a dom0
terminal.
Click the Qubes App Launcher (blue/grey "Q")
→ Open the Terminal Emulator (Xfce Terminal)
2. First try upgrading the Template.
This will only work if there is a new Point Release of the Template.
Execute the following command.
Notes:
- Template choice: Replace
qubes-template-package
with either:qubes-template-whonix-workstation-17
orqubes-template-whonix-gateway-17
, respectively. - Testers-Only: Testers should replace
--enablerepo=qubes-templates-community
with--enablerepo=qubes-templates-community-testing
.
Syntax:
qvm-template --enablerepo=qubes-templates-community upgrade <qubes-template-package>
For example, to reinstall and upgrade whonix-gateway-17
Template.
qvm-template --enablerepo=qubes-templates-community upgrade whonix-gateway-17
For example, to reinstall and upgrade whonix-workstation-17
Template.
qvm-template --enablerepo=qubes-templates-community upgrade whonix-workstation-17
3. Read the output of the above command. The following outcomes are possible, either:
- A) The Template is upgraded. In that case, skip step four below ("Reinstall the Template"); 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 Template"); OR - C) A Template upgrade is unsupported. This might happen if a non-Fedora based UpdateVM is used in conjunction with the
upgrade
option. See: UpdateVM Setting for further information; OR - D) An error has occurred, such as a networking issue.
4. Optional: Reinstall the Template.
If upgrade
at step two did not actually reinstall the Template, this means there is no new Point Release available at present. This also means the Template 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 Template version, then it will simply be reinstalled again.
Execute the following command.
Notes: Same notes as above apply.
Syntax:
qvm-template --enablerepo=qubes-templates-community reinstall <qubes-template-package>
For example, to reinstall whonix-gateway-17
Template.
qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-gateway-17
For example, to reinstall whonix-workstation-17
Template.
qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-workstation-17
Read the output of the above command. There are two possible outcomes, either:
- A) The Template was reinstalled; OR
- B) An error has occurred, such as a networking issue.
Settings[edit]
Use salt
to configure dom0
settings. [19]
sudo qubesctl state.sls qvm.anon-whonix
Optional Steps[edit]
Whonix Disposable Template[edit]
In Qubes R4 and above a whonix-workstation-17-dvm
Disposable Template can optionally be set up as a base for Disposables. [20]
In dom0
, run. [21]
sudo qubesctl state.sls qvm.whonix-workstation-dvm
Updates over Tor[edit]
Templates[edit]
To force all Template updates over Tor, use qubesctl
in dom0
. [22]
sudo qubesctl state.sls qvm.updates-via-whonix
To undo this setting, modify /etc/qubes-rpc/policy/qubes.UpdatesProxy
in dom0
. [23] 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
. [24]
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. [25]
Qubes Manager
→System
→Global Settings
→Dom0 UpdateVM:
sys-firewall
→OK
Enable AppArmor[edit]
AppArmor is enabled by default. No extra steps required.
Final Steps[edit]
Restart App Qubes[edit]
Any VMs based on the reinstalled Template must be restarted to reflect the updated file system.
Update and Launch Applications[edit]
Before starting applications in the Whonix-Workstation™ App Qube, update both Whonix-Gateway™ and Whonix-Workstation™ Templates.
To launch an application like Tor Browser:
Qubes App Launcher (blue/grey "Q")
→Domain: anon-whonix
→Tor Browser (AnonDist)
Done[edit]
The process of reinstalling Qubes-Whonix Templates is now complete.
Footnotes[edit]
- ↑ https://www.qubes-os.org/doc/how-to-reinstall-a-template/
- ↑
This is because the name of the Templates changed from:
whonix-gw-16
towhonix-gateway-17
whonix-workstation-16
towhonix-workstation-17
- ↑ 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 Template (whonix-gateway-17
) 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 - ↑
Upgrade Qubes
dom0
is required to make sure:- version file
/srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
contains the current version number of Whonix is up to date, - a recent version of Qubes repository definition files,
- Qubes salt,
- qubes-core-admin-addon-whonix,
- as well as qubes-mgmt-salt-dom0-virtual-machines are installed and up to date.
- version file
- ↑
Using
--show-output --console
is optional, recommended because of Qubes upstream bug:qubes-dom0-update
showsNo updates available
in case of network is down /qubes-dom0-update
fails to notice if repositories are unreachable / network is down - ↑
- ↑ Which is invoked by
qubes-dom0-update
. - ↑ Note the file extension
.repo.rpmnew
. - ↑
It should not be necessary to manually update that file because the Qubes
dom0
stable package should have updated it already. If it didn't, then the cause is general issues unspecific to Whonix. - ↑
This is currently not needed and discouraged:
1. In
dom0
open filewhonix.jinja
with root rights.sudo nano /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
2. Change
16
to17
.3. Save the file.
- ↑ The following Qubes issues are for developers understanding, reference only:
- ↑ qubes-dom0-update combined upgrade reinstall command
- ↑ phase out manual use of qubes-dom0-update by user / replace it by salt
- ↑ Dev/Qubes#salt
- ↑ For developers only, link to related source code file: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/whonix-workstation-dvm.sls
- ↑ Old command was the following: sudo qubesctl state.sls qvm.whonix-ws-dvm In that case your system is not updated, out-of-date.
- ↑
- By Qubes default, Qubes UpdatesProxy (RPC / qrexec based) is used to update Templates.
- Qubes: How to install software, technical details
- Qubes
salt
management stackqubesctl
- For developers only, related source code file: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/updates-via-whonix.sls
- ↑ How to change Template update method from Whonix to just another appvm?
- ↑
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
We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!