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]| 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 |
| 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.
|
| Preexisting Qubes-Whonix 18 Installations |
This is a notice for users who already have Qubes-Whonix 18 installed.
|
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.
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 .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 [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.rpmnewto the.repofile; or - Overwrite the
.repofile with the.repo.rpmnewfile:- 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.rpmnewdoes 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.![]()
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.
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
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 Manager→System→Global Settings→Dom0 UpdateVM:sys-whonix→OK
To revert this change, set Qubes' dom0 UpdateVM to sys-firewall or another preferred VM. [18]
Qubes Manager→System→Global Settings→Dom0 UpdateVM:sys-firewall→OK
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-whonix→Tor Browser (AnonDist)
Additional Information
[edit]Warnings
[edit]
It is recommended to refer to the following additional references:
- Known Issues
- Read and apply the Post Installation Security Advice.
- Follow Whonix Developments
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.
- ↑
- specifically: Qubes feature request: self-contained Qubes Templates including meta scripts (salt) / improve Qubes-Whonix installation usability (#6948)

- generally: Linux User Experience versus Commercial Operating Systems

- specifically: Qubes feature request: self-contained Qubes Templates including meta scripts (salt) / improve Qubes-Whonix installation usability (#6948)
- ↑
This is also true for other distribution Templates. For example, users of the Qubes
debian-12Template will not have all their App Qubes updated to the newdebian-13Template by default when it is downloaded. - ↑ For example, this could result in breakage if custom-installed applications in the old Template were not available in the new Template.
- ↑
- ↑
Upgrading Qubes
dom0is required to ensure:- The version file
/srv/formulas/base/virtual-machines-formula/qvm/whonix.jinjacontains the current version number of Whonix and is up to date. - A recent version of Qubes repository definition files.
- Qubes salt.
- qubes-core-admin-addon-whonix

.
- qubes-mgmt-salt-dom0-virtual-machines

, ensuring it is installed and up to date.
- The version file
- ↑
- ↑ This is invoked by
qubes-dom0-update. - ↑ Note the file extension
.repo.rpmnew. - ↑
The following
qvm-templatecommand is:- Optional.
- Useful because it has a progress indicator, while the subsequent
qubesctlcommand does not. (Qubes feature request: add salt download progress indicator
) It is very confusing to have a long-running download command with no progress bar, especially over Tor.
- Insufficient by itself - the subsequent
qubesctlcommand that follows is mandatory, as per phase out manual use of qubes-dom0-update by user / replace it by salt
and Dev/Qubes#salt.
--enablerepo=qubes-templates-community:--enablerepo=qubes-templates-communitycan be omitted if the Qubes Community Templates Repository is already enabled indom0.- 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-communityis poor usability, since users cannot copy from their VM browser (where they are most likely reading this) todom0. But too many people reported this issue. had to enable Qubes templates community repository
- If the Qubes Community Templates Repository is not enabled in
dom0, explicitly add--enablerepo=qubes-templates-communityor enable it through editing the/etc/yum.repos.d/qubes-templates.repofile in dom0.
In
dom0.1 Open file
/etc/yum.repos.d/qubes-templates.repoin 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-communityshould no longer be required.5 Report.
Please report if this step was necessary for you!
- ↑
- Do not interrupt the salt process once it has started, or this can lead to an unstable system

.
qubesctl: This is a Qubes command, not from Whonix. Advanced users may refer to Qubes salt management stackqubesctl
for further information about
qubesctland Qubes salt.- If Templates were not previously downloaded using the above
qvm-templatecommand, then thequbesctlcommand would also download both Whonix-Gateway and Whonix-Workstation Templates. - Related source code files, for developer reference only:
- Do not interrupt the salt process once it has started, or this can lead to an unstable system
- ↑
No progress indicator is shown. Qubes feature request: add salt download progress indicator

- ↑
If
qubesctlstill does not work, try shutting down Qubes OS and rebooting the machine. Please report if this step was necessary for you! - ↑
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

- ↑
There was a Qubes bug that may cause the Disposable Template to run instead of the Disposable

. 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.
- ↑
- By Qubes default, Qubes UpdatesProxy (RPC / qrexec based) is used to update Templates.
- Qubes: How to install software, technical details

- Qubes
saltmanagement 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
dom0terminal. qubes-prefs updatevm sys-whonix - ↑
To revert this change in
dom0terminal, 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 13 year success story and maybe DONATE!




