Actions

Reinstall Qubes-Whonix ™ TemplateVMs - Stable Version

From Whonix

< Qubes
Donate
Donate


Introduction[edit]

FREE

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

Info Note: If you have Qubes-Whonix ™ 14 installed and want to get Qubes-Whonix ™ 15 there is no need to follow the instructions on this very page. Head over to Install Qubes-Whonix ™ guide instead because it is easier. [2]

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.

Ambox warning pn.svg.png 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]

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. [4]

Info 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.

You can either:

Reinstall the Whonix TemplateVM[edit]

Qubes Version[edit]

UpdateVM Setting[edit]

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. [5]

1. Create a new VM named dom0-updatevm.

  • Qubes VM Manager → VM → Create AppVM
    • Name and label: Name the AppVM. Don't 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-28.
    • 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 the user wants non-torified, clearnet Qubes dom0 updates, 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 the user wants torified Qubes dom0 updates, 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]

To launch a dom0 terminal, click the Qubes App Launcher (blue/grey "Q") and then open the Terminal Emulator (Xfce Terminal).

Qubes-whonix1.png

Upgrade Qubes dom0. This step is mandatory. [9] 

sudo qubes-dom0-update

Configure salt using Qubes dom0 Community Testing Repository[edit]

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

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.

Enable qubes-templates-community-testing repository.

1. 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]

In dom0.

Open file whonix.jinja with root rights. [13] 

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

Change 14 to 15.

Save.

Please report if this step was necessary or unnecessary for you!

Reinstall[edit]

To launch a dom0 terminal, click the Qubes App Launcher (blue/grey "Q") and then open the Terminal Emulator (Xfce Terminal).

Qubes-whonix1.png

In the instructions below, first it will be checked if there is 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]

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

Read the output of the above command. Possible outcomes, either:

  • A) The TemplateVM gets upgraded. In that case you can skip the below section "Reinstall the TemplateVM". OR
  • B) Above commands might finish relatively quickly and might say No new updates available. In that case, proceed with the section below "Reinstall the TemplateVM". OR
  • C) 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 more information. OR
  • D) Some error such as networking issue.

Reinstall the TemplateVM.

If above --action=upgrade did not actually reinstall the TemplateVM, it means that there is no new Point Release available at this point. It however also means, that the TemplateVM has not been actually reinstalled. To actually reinstall the TemplateVM, proceed as documented below.

If you are not sure, below commands are safe in any case. Should you already have the latest TemplateVM version, in worst case it would be re-installed yet another time, which is ok.

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. Possible outcomes, either:

  • A) The TemplateVM got reinstalled. OR
  • B) Some error such as networking issue.

Settings[edit]

Use salt for dom0 settings setup. [15]

Ambox warning pn.svg.png This step is mandatory. [16] 

sudo qubesctl state.sls qvm.anon-whonix

Optional Whonix DVM Template VM[edit]

In Qubes R4 and above, a whonix-ws-15-dvm DVM Template can optionally be set up as a base for Disposable VMs. [17]

In dom0, run. 

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

Optional 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 Qubes/UpdatesProxy.

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

Optional: 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 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 sys-whonix and anon-whonix TemplateBasedVMs to benefit from the new kernel parameters.[23] It is also important for users 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

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)

To learn about known bugs affecting this release, see here.

Done[edit]

The process to reinstall Whonix TemplateVMs is now complete. Users should disregard the chapter Manual Reinstallation below.

Footnotes[edit]

  1. ↑ https://qubes-os.org/doc/reinstall-template/ [archive]
  2. ↑ This is because the name of the TemplateVMs changed from:
    • whonix-gw-14 to whonix-gw-15
    • whonix-ws-14 to whonix-ws-15
  3. ↑ https://whonix.org/Dev/Technical_Introduction#With_more_technical_terms [archive]
  4. ↑ Using salt.
  5. ↑
    • sys-net → sys-firewall → sys-whonix → UpdateVM
    • UpdateVM → sys-whonix → sys-firewall → sys-net
  6. ↑ 
    qvm-prefs updatevm-name netvm sys-whonix
  7. ↑ 
    qvm-prefs updatevm-name netvm sys-whonix
  8. ↑ 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
  9. ↑
  10. ↑
  11. ↑ Which is invoked by qubes-dom0-update.
  12. ↑ Note the file extension .repo.rpmnew.
  13. ↑
  14. ↑ qubes-dom0-update combined --action=upgrade --action=reinstall command [archive]
  15. ↑ Dev/Qubes#salt
  16. ↑ phase out manual use of qubes-dom0-update by user / replace it by salt [archive]
  17. ↑ https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/whonix-ws-15-dvm.sls [archive]
  18. ↑
  19. ↑ https://groups.google.com/forum/?_escaped_fragment_=topic/qubes-users/_jI2uWPPMMA#!topic/qubes-users/_jI2uWPPMMA [archive]
  20. ↑ Or manually set the torified UpdateVM in dom0 terminal. 
    qubes-prefs updatevm sys-whonix
  21. ↑ To revert this change in dom0 terminal, run. 
    qubes-prefs updatevm sys-firewall
  22. ↑ 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 15 is Debian buster based.
  23. ↑ Since Qubes R3.0, TemplateBasedVMs inherit the kernelopts setting of their TemplateVM [archive].

We are looking for help in managing our social media accounts. Are you interested?

https [archive] | (forcing) onion [archive]
Follow: Twitter.png Facebook.png 1280px-Gab text logo.svg.png Rss.png 1024px-Telegram 2019 Logo.svg.png Discourse logo.svg

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png

Share: Twitter | Facebook

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.

Copyright (C) 2012 - 2019 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.

Monero donate whonix.png

Retrieved from "https://www.whonix.org/w/index.php?title=Qubes/Reinstall&oldid=49021"