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.
Notices[edit]
Table: Qubes-Whonix™ Release Notices
Notice | Description |
---|---|
Qubes 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 broken |
Usability |
The instructions on this wiki page have bad usability. These are mostly out of control of the Whonix project. See footnote for more information. [1] |
Qubes-Whonix 16 to Qubes-Whonix 17 Release Upgrade | This is a notice for users who currently have Qubes-Whonix 16 installed.
If Qubes-Whonix 16 is installed and you want to get Qubes-Whonix 17, there is no need to uninstall Qubes-Whonix 16 before proceeding according to the instructions on this wiki page. This is because the new templates ( In this case, App Qubes that were previously configured to use Qubes-Whonix 16 templates will keep using them -- the Templates of any App Qubes are not automatically changed to the newly installed Qubes-Whonix 16 templates. This is a Qubes default and unspecific to Qubes-Whonix. [2] Therefore, a manual change must be applied to 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] After the Qubes-Whonix installation has finished, it is recommended to manually change the setting of any App Qubes still using Qubes-Whonix 16 Templates to the Qubes-Whonix 17 Templates. [4] A wholly different, alternative option is to ignore all the advice on this wiki page and instead perform a Release Upgrade according to the Release Upgrade Whonix 16 to Whonix 17 instructions. |
Preexisting Qubes-Whonix 17 Installations |
This is a notice for users who already have Qubes-Whonix 17 installed. If any user data was stored in Qubes-Whonix VMs, before re-installation, back up any existing data. If you are already running Qubes-Whonix 17, it must be uninstalled before a complete re-installation is performed. This is also necessary when Qubes-Whonix 17 is bundled as part of future Qubes releases, and auto-configuration is selected during the installation. Choose re-installation options A) OR B). (listed in order of preference)
|
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. [5] [6]
sudo qubes-dom0-update --show-output --console
3. Done.
dom0 upgrade has been completed.
Version Number Verification[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. [7] [8] [9]
5. Done.
Version number verification has been completed.
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
. [10]
To download Whonix-Gateway and Whonix-Workstation run this command:
qvm-template install --enablerepo=qubes-templates-community whonix-gateway-17 whonix-workstation-17
3. Configure sys-whonix
and anon-whonix
safely. [11]
In dom0
, run. [12]
sudo qubesctl state.sls qvm.anon-whonix
4. In case of issues.
Only in case of issues, refer to the footnotes for troubleshooting tips. [13] 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.
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]
In Qubes R4 and above a whonix-workstation-17-dvm
Disposable Template can optionally be set up as a base for Disposables. [14]
In dom0
, run. [15]
sudo qubesctl state.sls qvm.whonix-workstation-dvm
There is a Qubes bug that may cause the Disposable Template to run instead of the Disposable. Might be fixed in Qubes R4.2. Unspecific to Whonix. If this happens, just log off and back on. There is no need to reinstall or set up anything.
Updates over Tor[edit]
Templates[edit]
To force all Template updates over Tor, use qubesctl
in dom0
. [16]
sudo qubesctl state.sls qvm.updates-via-whonix
To undo this setting, modify /etc/qubes-rpc/policy/qubes.UpdatesProxy
in dom0
. [17] 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
. [18]
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. [19]
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 these 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
- ↑ This is also true for other distribution Templates. For example, users of the Qubes
debian-10
Template will not have all their App Qubes updated to the newdebian-11
Template 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.
- ↑
- ↑
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 - ↑
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:
- ↑
The following
qubes-dom0-update
command is:- Optional.
- Useful because it has a progress indicator while the subsequent
qubesctl
command does not. (Qubes feature request: add salt download progress indicator) It very confusing to have a long running download command with progress bar, specifically over Tor. - Insufficient by itself - the subsequent
qubesctl
command that follow 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-community
can be omitted if Qubes Community Templates Repository is already enabled indom0
.- Qubes Community Templates Repository should already be enabled as per Qubes default unless disabled by user, restored Qubes-Whonix™ from backup or some other edge case.
- Recommending to type
--enablerepo=qubes-templates-community
is bad 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 Qubes Community Templates Repository is not enabled in
dom0
, explicitly add--enablerepo=qubes-templates-community
or enable through editing dom0 file/etc/yum.repos.d/qubes-templates.repo
.
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. Command line parameter
--enablerepo=qubes-templates-community
should be no longer required.5. Report.
Please report if step this was necessary for you!
- ↑
- Do not interrupt the salt process once it has started or this can lead to an unstable system.
qubesctl
: Is a command by Qubes, not Whonix. Advanced users could may look at Qubes salt management stackqubesctl
for further information aboutqubesctl
and Qubes salt.- If Templates were not previously downloaded already by using above
qubes-dom0-update
command, then thequbesctl
command would also download both Whonix-Gateway and Whonix-Workstation Templates. - Related source code files, reference for developers only:
- ↑ No progress indicator is shown. Qubes feature request: add salt download progress indicator
- ↑
If
qubesctl
still 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
- ↑ 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!