How-to: Install Qubes-Whonix

From Whonix
(Redirected from Qubes/Install/Testing)
Jump to navigation Jump to search
Documentation Previous page: Qubes/Why use Qubes over other Virtualizers Index page: Documentation Next page: Qubes/Reinstall How-to: Install Qubes-Whonix

Getting started with Qubes-Whonix in 4 steps.

Here you can find installation instructions, release notices, disposable template setup, updates over Tor, and more.

1 Notices

[edit]
Qubes-Whonix Release Notices
Notice Description
Version Support
Footnotes

Novice or intermediate users can generally ignore footnotes (like 1) unless experiencing difficulties or having questions. See also introduction chapter Whonix Footnotes and References.

Known Issues
Other Issues

In case technical issues are experienced, such as a broken dom0 or a broken qubes-dom0-update, these are Qubes issues and unspecific to Whonix. They should therefore either be reported to qubes-issuesarchive.org iconarchive.today icon, or added as a comment to an existing issue there (if appropriate). This is further elaborated in What to post in this Qubes-Whonix forum and what not.archive.org iconarchive.today icon

Usability

The instructions on this wiki page have poor usability. These issues are mostly outside the control of the Whonix project. See the footnote for more information. [1]

Qubes-Whonix 17 to Qubes-Whonix 18 Release Upgrade This is a notice for users who currently have Qubes-Whonix 17 installed.

Availability and Qubes-Whonix Support: Qubes R4.2 versus Qubes R4.3?

  • Qubes R4.2: Qubes-Whonix 18 unavailable. Qubes-Whonix 18 won't be available for Qubes R4.2.
    • Release status: Even though Qubes R4.3 is only available as a release candidate (RC) at the time of writing,
    • Expected release: A stable release of Qubes R4.3 (and Qubes-Whonix 18) is probably not far away.
    • Upgrade recommendation: Qubes-Whonix 17 users on Qubes R4.2 are encouraged to consider upgrading to Qubes-Whonix 18 on Qubes R4.3 as soon as possible.
    • Maintenance situation: Qubes-Whonix 18 is what developers are using and where the development focus is. It comes with much newer packages. Qubes-Whonix is a small project and does not have a dedicated team for oldstable support. Therefore, oldstable support is maintained as a side project. More details: decide availability of Kicksecure and Whonix 18 (Debian trixie based) on Qubes R4.2 versus R4.3 #10219archive.org iconarchive.today icon
  • Qubes R4.3: Qubes-Whonix 18 is available.Qubes-Whonix 18 release announcementarchive.org iconarchive.today icon
  • Upgrade coexistence: If Qubes-Whonix 17 is installed and you want to get Qubes-Whonix 18, there is no need to uninstall Qubes-Whonix 17 before proceeding with the instructions on this wiki page. This is because the new Templates (whonix-workstation-18, whonix-gateway-18) will be installed alongside the old Templates (whonix-workstation-17, whonix-gateway-17).
  • Template persistence: In this case, App Qubes that were previously configured to use Qubes-Whonix 17 Templates will keep using them -- the Templates of any App Qubes are not automatically changed to the newly installed Qubes-Whonix 18 Templates. This is a Qubes default and unspecific to Qubes-Whonix. [2]
  • Manual change required: Therefore, a manual change must be applied to the App Qubes' settings by the user. The rationale is to prevent unexpected changes of an App Qube's Template without the user's consent. [3]
  • Recommendation: After the Qubes-Whonix installation has finished, it is recommended to manually change the settings of any App Qubes still using Qubes-Whonix 17 Templates to the Qubes-Whonix 18 Templates. [4]
Preexisting Qubes-Whonix 18 Installations

This is a notice for users who already have Qubes-Whonix 18 installed.

  • Backup reminder: If any user data was stored in Qubes-Whonix VMs, back up any existing data before re-installation.
  • Uninstallation requirement: If you are already running Qubes-Whonix 18, it must be uninstalled before a complete re-installation is performed. This is also necessary when Qubes-Whonix 18 is bundled as part of future Qubes releases, and auto-configuration is selected during the installation.
  • Re-installation options: Choose re-installation option A) OR B). (Listed in order of preference)

2 Update dom0

[edit]

1 Launch a dom0 terminal.
Click the Qubes App Launcher (blue/grey "Q")Open the Terminal Emulator (Qterminal)

2 Upgrade Qubes dom0. This step is mandatory. [5]

sudo qubes-dom0-update

3 Done.

The dom0 upgrade has been completed.

3 Configure salt using Qubes dom0 Community Testing Repository

[edit]

Optional.

Info Testers only.

If you are an interested tester, click Learn More on the right.

The following command will configure Qubes dom0 salt to use qubes-templates-community-testing for downloading Whonix. [6]

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

The following steps to enable the qubes-templates-community-testing repository should no longer be necessary. Please report if these steps were necessary for you.

If you are an interested tester, click Learn More on the right.

1. Enable qubes-templates-community-testing repository.

View the Qubes Templates .repoarchive.org iconarchive.today icon 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 [7] preserves user changes by saving updates to /etc/yum.repos.d/qubes-templates.repo.rpmnew [8] 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 already has [qubes-templates-community-testing].

4 Download and Configure Whonix Templates

[edit]

Download Whonix Templates and Configure sys-whonix and anon-whonix.

1 Download speed notice.

This downloading procedure can take a long time to finish. Fast Internet connections take only a few minutes, while slow connections can take twenty minutes or more (it is far slower over Tor).

2 Download both Whonix-Gateway and Whonix-Workstation Templates.

In dom0. [9]

To download Whonix-Gateway and Whonix-Workstation, select your version of Qubes OS and.

Qubes R4.2

Run this command:

qvm-template install --enablerepo=qubes-templates-community whonix-gateway-17 whonix-workstation-17

Qubes R4.3

Run this command:

Note: The "-testing" in the following command can soon be removed.archive.org iconarchive.today icon

qvm-template install --enablerepo=qubes-templates-community-testing whonix-gateway-18 whonix-workstation-18

3 Configure sys-whonix and anon-whonix safely. [10]

In dom0, run. [11]

sudo qubesctl state.sls qvm.anon-whonix

4 In case of issues.

Only in case of issues, refer to the footnotes for troubleshooting tips. [12] Otherwise, proceed.

5 Done.

Download and installation of Qubes-Whonix has been completed.

6 Next steps.

See below for additional optional configurations and additional information.

5 Support the Future of Whonix

[edit]

Whonix is made possible thanks to the donation of people like you.

Please support the Whonix development with a donation.

Donate to Whonix

Optional Steps

[edit]

Whonix Disposable Template

[edit]

Qubes-Whonix Disposable Template can optionally be set up as a base for Disposables. [13]

In dom0, run.

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

[14]

Updates over Tor

[edit]

Templates

[edit]

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

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

To undo this setting, modify,

  • Qubes R4.2: /etc/qubes-rpc/policy/qubes.UpdatesProxy
  • Qubes R4.3: /etc/qubes/policy.d/50-config-updates.policy

in dom0. [16] 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. [17]

  • Qube ManagerSystemGlobal SettingsDom0 UpdateVM: sys-whonixOK

To revert this change, set Qubes' dom0 UpdateVM to sys-firewall or another preferred VM. [18]

  • Qubes ManagerSystemGlobal SettingsDom0 UpdateVM: sys-firewallOK

Enable AppArmor

[edit]

AppArmor is enabled by default. No extra steps required.

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-whonixTor Browser (AnonDist)

Additional Information

[edit]

Warnings

[edit]

Whonix first time users warning Warning:

  • If you do not know what metadata or a man-in-the-middle attack is.
  • If you think nobody can eavesdrop on your communications because you are using Tor.
  • If you have no idea how Whonix works.

Then read the Design and Goals, Whonix and Tor Limitations and Tips on Remaining Anonymous pages to decide whether Whonix is the right tool for you based on its limitations.

It is recommended to refer to the following additional references:

Footnotes

[edit]

Novice or intermediate users can generally ignore footnotes (like 1) unless experiencing difficulties or having questions. See also introduction chapter Whonix Footnotes and References.

  1. This is also true for other distribution Templates. For example, users of the Qubes debian-12 Template will not have all their App Qubes updated to the new debian-13 Template by default when it is downloaded.
  2. For example, this could result in breakage if custom-installed applications in the old Template were not available in the new Template.
  3. Upgrading Qubes dom0 is required to ensure: Older, similar references:
  4. This is invoked by qubes-dom0-update.
  5. Note the file extension .repo.rpmnew.
  6. The following qvm-template command is:
    • Optional.
    • Useful because it has a progress indicator, while the subsequent qubesctl command does not. (Qubes feature request: add salt download progress indicatorarchive.org iconarchive.today icon) It is very confusing to have a long-running download command with no progress bar, especially over Tor.
    • Insufficient by itself - the subsequent qubesctl command that follows is mandatory, as per phase out manual use of qubes-dom0-update by user / replace it by saltarchive.org iconarchive.today icon and Dev/Qubes#salt.
    • --enablerepo=qubes-templates-community:
      • --enablerepo=qubes-templates-community can be omitted if the Qubes Community Templates Repository is already enabled in dom0.
      • The Qubes Community Templates Repository should already be enabled by default, unless disabled by the user, restored Qubes-Whonix from backup, or in some other edge case.
      • Recommending typing --enablerepo=qubes-templates-community is poor usability, since users cannot copy from their VM browser (where they are most likely reading this) to dom0. But too many people reported this issue. had to enable Qubes templates community repositoryarchive.org iconarchive.today icon
      • If the Qubes Community Templates Repository is not enabled in dom0, explicitly add --enablerepo=qubes-templates-community or enable it through editing the /etc/yum.repos.d/qubes-templates.repo file in dom0.

    In dom0.

    1 Open file /etc/yum.repos.d/qubes-templates.repo in a text editor with root rights.

    sudo nano /etc/yum.repos.d/qubes-templates.repo

    2 In section [qubes-templates-community], add the following.

    enabled = 1

    3 Save.

    4 Done.

    Qubes Community Templates Repository has been enabled. The command line parameter --enablerepo=qubes-templates-community should no longer be required.

    5 Report.

    Please report if this step was necessary for you!

  7. No progress indicator is shown. Qubes feature request: add salt download progress indicatorarchive.org iconarchive.today icon
  8. If qubesctl still does not work, try shutting down Qubes OS and rebooting the machine. Please report if this step was necessary for you!
  9. 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.slsarchive.org iconarchive.today icon
  10. There was a Qubes bug that may cause the Disposable Template to run instead of the Disposablearchive.org iconarchive.today icon. This might be fixed in Qubes R4.2 and above. Unspecific to Whonix. If this happens, just log off and back on. There is no need to reinstall or set up anything.
  11. How to change Template update method from Whonix to just another appvm?archive.org iconarchive.today icon
  12. Or manually set the torified UpdateVM in dom0 terminal. qubes-prefs updatevm sys-whonix
  13. To revert this change in dom0 terminal, run. qubes-prefs updatevm sys-firewall
Notification image

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 13 year success story and maybe DONATE!