Introduction[edit]

On occasion it is necessary to reinstall a Whonix ™ template from the Qubes repository. ^[1]

Note: If Qubes-Whonix ™ 15 is installed and you want to get Qubes-Whonix ™ 16, it is unnecessary to follow the instructions on this page. Refer to Install Qubes-Whonix ™ instructions 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: 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]

If the Whonix ™ Template is broken, misconfigured or potentially compromised, discontinue using any App Qubes based on the affected template.

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 ^[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 Template 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 ™ template instructions below.

Reinstall the Whonix ™ template[edit]

Qubes Version[edit]

Qubes R4.0 or above required! ^[archive]

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 than 34 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 of dom0-updatevm for example to sys-firewall.

Qube Manager → dom0-updatevm → Qube settings → Networking: sys-firewall → OK ^[6]

Option B: If torified Qubes dom0 updates are preferred, set the NetVM of dom0-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.

^[8]

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

sudo qubes-dom0-update

Configure salt using Qubes dom0 Community Testing Repository[edit]

Testers only.

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 ™. ^[10]

sudo qubesctl top.enable qvm.whonix-testing pillar=true

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 ^[archive] file.

cat /etc/yum.repos.d/qubes-templates.repo

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
```
  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]

Verify whonix_version is 16.

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.

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

sudo cat /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja

Example output:

{% set whonix_version = salt['pillar.get']('qvm:whonix:version', '16') %}
{% set whonix_repo = salt['pillar.get']('qvm:whonix:repo', '[omitted for brevity]') %}

{% set whonix_version = salt['pillar.get']('qvm:whonix:version', '16') %}
{% set whonix_repo = salt['pillar.get']('qvm:whonix:repo', '[omitted for brevity]') %}

If it shows something else, then Qubes dom0 is outdated. In that case, it is not possible to continue. ^[13] ^[14]

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 (--action=upgrade).
If no newer Template version is available, reinstall the existing version (--action=reinstall).

Unfortunately there is no combined upgrade and reinstall command. ^[15]

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. Replace qubes-template-package with either: qubes-template-whonix-ws-16 or qubes-template-whonix-gw-16, respectively.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade <qubes-template-package>

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade <qubes-template-package>

For example, to reinstall and upgrade whonix-gw-16 Template.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-gw-16

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-gw-16

For example, to reinstall and upgrade whonix-ws-16 Template.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-ws-16

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=upgrade qubes-template-whonix-ws-16

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 --action=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 --action=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. Replace qubes-template-package with either: qubes-template-whonix-ws-16 or qubes-template-whonix-gw-16, respectively.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall <qubes-template-package>

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall <qubes-template-package>

For example, to reinstall whonix-gw-16 Template.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-gw-16

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-gw-16

For example, to reinstall whonix-ws-16 Template.

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws-16

sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws-16

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]

This step is mandatory. ^[16]

Use salt to configure dom0 settings. ^[17]

sudo qubesctl state.sls qvm.anon-whonix

sudo qubesctl state.sls qvm.anon-whonix

Optional Steps[edit]

Whonix ™ Disposable Template[edit]

In Qubes R4 and above a whonix-ws-16-dvm Disposable Template can optionally be set up as a base for Disposables. ^[18]

In dom0, run.

sudo qubesctl state.sls qvm.whonix-ws-dvm

sudo qubesctl state.sls qvm.whonix-ws-dvm

Updates over Tor[edit]

Templates[edit]

To force all Template updates over Tor, use qubesctl in dom0. ^[19]

sudo qubesctl state.sls qvm.updates-via-whonix

sudo qubesctl state.sls qvm.updates-via-whonix

To undo this setting, modify /etc/qubes-rpc/policy/qubes.UpdatesProxy in dom0. ^[20] 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. ^[21]

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. ^[22]

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-16 and whonix-ws-16 Templates. ^[23] After these settings are applied to the Whonix ™ templates, the sys-whonix (ProxyVM) and anon-whonix (App Qube) will inherit the AppArmor kernel settings.

It is unnecessary to recreate the sys-whonix and anon-whonix App Qubes to benefit from the new kernel parameters. ^[24] 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-16 kernelopts

qvm-prefs -g whonix-gw-16 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-16 kernelopts "nopat apparmor=1 security=apparmor"

qvm-prefs -s whonix-gw-16 kernelopts "nopat apparmor=1 security=apparmor"

qvm-prefs -s sys-whonix 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-16 kernelopts

qvm-prefs -g whonix-gw-16 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 $?

sudo aa-status --enabled ; echo $?

The output should show.

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-16 kernelopts

qvm-prefs -g whonix-ws-16 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-16 kernelopts "nopat apparmor=1 security=apparmor"

qvm-prefs -s whonix-ws-16 kernelopts "nopat apparmor=1 security=apparmor"

qvm-prefs -s anon-whonix 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-16 kernelopts

qvm-prefs -g whonix-ws-16 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 App Qube and confirm AppArmor is now active.

sudo aa-status --enabled ; echo $?

sudo aa-status --enabled ; echo $?

The output should show.

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://qubes-os.org/doc/reinstall-template/ ^[archive]
↑
This is because the name of the Templates changed from:
- whonix-gw-15 to whonix-gw-16
- whonix-ws-15 to whonix-ws-16
↑ 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
↑
```
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-gw-16) and/or its Whonix-Gateway ™ ProxyVM (sys-whonix) are no longer trusted, then configure Qubes dom0 to use a different UpdateVM by applying the following steps. TODO
↑
This 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 ^[archive],
- as well as qubes-mgmt-salt-dom0-virtual-machines ^[archive] are installed and up to date.
Older, similar references:
↑
↑ Which is invoked by qubes-dom0-update.
↑ Note the file extension .repo.rpmnew.
↑
Testers-only: 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 ™.
1. In dom0 open file whonix.jinja with root rights.
sudo nano /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
sudo nano /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja
2. Change 15 to 16.
3. Save the file.
↑
The following Qubes issues are for developers understanding, reference only:
↑ 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
↑ For developers only, link to related source code file: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/whonix-ws-16-dvm.sls ^[archive]
↑
- By Qubes default, Qubes UpdatesProxy (RPC / qrexec based) is used to update Templates.
- Qubes: How to install software, technical details ^[archive]
- Qubes salt management stack qubesctl ^[archive]
- For developers only, related source code file: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/updates-via-whonix.sls ^[archive]
↑ How to change TemplateVM update method from Whonix to just another appvm? ^[archive]
↑
Or manually set the torified UpdateVM in dom0 terminal.
```
qubes-prefs updatevm sys-whonix
```
qubes-prefs updatevm sys-whonix
↑
To revert this change in dom0 terminal, run.
```
qubes-prefs updatevm sys-firewall
```
qubes-prefs updatevm sys-firewall
↑ Debian has enabled AppArmor by default since the buster release, but Fedora has not. This matters because Qubes is Fedora-based and therefore uses the dom0 (not VM) kernel by default. Therefore this step is still required even though Whonix ™ is based on a recent enough Debian version.
↑ Since Qubes R3.0, App Qubes inherit the kernelopts setting of their Template ^[archive].