Update Qubes-Whonix™
Donate
How to update Qubes-Whonix.
End-of-life Software[edit]
It is inadvisable to run software that has reached end-of-life status. Developers do not fix existing defects, bugs or vulnerabilities in this case, leading to serious security risks.
For example, in 2018 VLC Media Player in Debian jessie
had reached end-of-life status in May of that year. In that case, Whonix users who did not utilize a different media player were at risk, because VLC in Debian jessie has unpatched security vulnerabilities. This VLC vulnerability does not apply to the current stable Whonix 17 release which is based on Debian bookworm.
Installing Additional Software[edit]
See Install Software.
Updates[edit]
Standard Update vs Release Upgrade[edit]
This procedure is for normal ("everyday") updates of Qubes-Whonix and will not perform a Release Upgrade.
Before applying a release upgrade, it is recommended to first complete a standard update in both the whonix-gateway-17 and whonix-workstation-17 Templates, via xfce4-terminal:
Qubes App Menu(blue/grey "Q")→Template: whonix-gateway-17→xfce4-terminalQubes App Menu(blue/grey "Q")→Template: whonix-workstation-17→xfce4-terminal
Afterward, perform the Standard Update Steps below in both terminals.
Warnings[edit]
- At least once a day, Qubes users should update the system package lists in all Templates, Standalones and
dom0with the latest version information on new and updated packages that are available for download. [1] - Below are some warnings and issues which are general Qubes bugs and unspecific to Qubes-Whonix. Primary sources from Qubes OS are referenced as links with specific citations.
Quote Qubes OS "How to update" warning:
Warning: Updating exclusively with direct commands such as
qubes-dom0-update,dnf update, andapt updateis not recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend first using the Qubes Update tool or its command-line equivalents, as described below, then using the direct commands for confirmation (see #6585
- Qubes Update tool
- For updating using command-line, refer to Qubes OS "How to update":
The situation is however complicated due to Qubes Updater Issues, most notably such as:
Standard Update Steps[edit]
Note: Updating Tor Browser is a separate issue; see Update Tor Browser.
1. Update the Package Lists
At the time of writing, it is discouraged to update whonix-gateway-17 and whonix-workstation-17 Template packages lists using Qube Manager (Qube Manager → left-click whonix-gateway-17 or whonix-workstation-17 → Update qube system (blue arrow)). [2]
For similar reasons, it is also discouraged to open a terminal in the Template and run.
sudo apt update
The output should look similar to this.
Hit:1 https://deb.qubes-os.org/r4.0/vm bookworm InRelease Hit:2 tor+https://deb.debian.org/debian bookworm InRelease Hit:3 tor+https://deb.whonix.org bullseye bookworm Hit:4 tor+https://deb.debian.org/debian bookworm-updates InRelease Hit:5 tor+https://fasttrack.debian.net/debian bookworm-fasttrack InRelease Hit:6 tor+https://deb.debian.org/debian-security bookworm-security InRelease Hit:7 tor+https://deb.debian.org/debian bookworm-backports InRelease Reading package lists... Done
If an error message like this appears. [3]
Hit:1 https://deb.qubes-os.org/r4.0/vm bookworm InRelease Ign:2 tor+https://deb.debian.org/debian bookworm InRelease ... Err:12 tor+http://5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion/ bookworm/updates Release Connection failed Reading package lists... Done E: The repository 'tor+http://5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion/ bookworm/updates Release' does no longer have a Release file. N: Updating from such a repository can't be done securely, and is therefore disabled by default. N: See apt-secure(8) manpage for repository creation and user configuration details. Done.
Or this.
500 Unable to connect
Then something went wrong. It could be:
- A temporary Tor exit relay or server failure that should resolve itself; or
- One or more Onion Services might be non-functional.
In the first case, check if the network connection is functional by changing the Tor circuit and/or run systemcheck to try and diagnose the problem. In the second case, try setting clearnet repository links before attempting to update again.
Sometimes a message like this will appear.
Could not resolve 'security.debian.org'
It that case, it helps to run.
nslookup security.debian.org
And then try again.
2. Upgrade
If using a terminal, run the following command to install the latest system package versions. [4]
sudo apt full-upgrade
Please note if the Whonix APT Repository was disabled (see Disable Whonix APT Repository), then manual checks are required for new Whonix releases along with manual installation from source code.
3. Never Install Unsigned Packages!
If a message like this appears.
WARNING: The following packages cannot be authenticated! thunderbird Install these packages without verification [y/N]?
Then do not proceed! Press N and <enter>. Running apt update again should fix the problem. If not, something is broken or it is a Man-in-the-Middle Attack, which is not that unlikely since updates are retrieved over Tor exit relays and some of them are malicious. Changing the Tor circuit is recommended if this message appears.
4. Signature Verification Warnings
There should be no signature verification warnings at present; if it occurs, it will look similar to this.
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: https://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681
Caution is required in this case, even though apt will automatically ignore repositories with expired keys or signatures, and no upgrades will be received from that repository. Unless the issue is already known or documented, it should be reported for further investigation.
There are two possible reasons why this could happen. Either there is an issue with the repository that the contributors have yet to fix or the user is the victim of a Man-in-the-Middle Attack. [5] The latter is not a big issue, since no malicious packages are installed. Further, it may automatically resolve itself after a period of time when a different, non-malicious Tor exit relay is used, or following a manual change of the Tor circuit.
In the past, various apt repositories were signed with an expired key. To inspect how the documentation appeared at that point, please click on Expand on the right.
For instance, the Tor Project's apt repository key had expired and the following warning appeared.
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: https://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 W: Failed to fetch https://deb.torproject.org/torproject.org/dists/stable/Release W: Some index files failed to download. They have been ignored, or old ones used instead.
This issue had already been reported. There was no immediate danger and it could have safely been ignored. Just make sure to never install unsigned packages as explained above.
For another example, see the more recent Whonix apt repository keyexpired error.
Although an unlikely outcome, please report any other signature verification errors if/when they appear.
5. Changed Configuration Files
Be careful if a message like this appears.
Setting up ifupdown ... Configuration file `/etc/network/interfaces' ==> Modified (by you or by a script) since installation. ==> Package distributor has shipped an updated version. What would you like to do about it ? Your options are: Y or I : install the package contributor's version N or O : keep your currently-installed version D : show the differences between the versions Z : background this process to examine the situation The default action is to keep your current version. *** interfaces (Y/I/N/O/D/Z) [default=N] ? N
It is safest to press y, but any customized settings will be lost (these can be re-added afterwards). [6] [7]
See also:
6. Shutdown the Template
Shutdown the Template from Qube Manager: Qube Manager → right-click on Template → Shutdown VM or via the contextual menu.
7. Restart/Update Whonix VMs
If new updates were available and installed, it is necessary to either:
- Restart any running Whonix-Gateway™ ProxyVMs (
sys-whonix) or Whonix-Workstation™ App Qube instances (anon-whonix) so they are updated; or - Apply the same update process in any running VMs if an immediate restart is inconvenient.
Note: If any dom0 packages were upgraded during Qubes system updates, reboot the computer to profit from any security updates.
Non-functional Onion Services[edit]
Sometimes the Debian, Whonix or Qubes onion servers are non-functional. This means updates cannot be completed automatically and an error message similar to below will appear.
user@host:~$ sudo apt update Hit:1 https://deb.debian.org/debian-security bookworm-security InRelease Hit:2 tor+http://deb.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion bookworm InRelease Ign:3 https://deb.debian.org/debian bookworm InRelease Hit:4 https://deb.whonix.org bookworm InRelease Hit:5 https://deb.debian.org/debian bookworm Release Err:7 tor+http://5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion bookworm/updates InRelease SOCKS proxy socks5h://localhost:9050 could not connect to 5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion (0.0.0.0:0) due to: Host unreachable (6) Err:8 tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian bookworm InRelease SOCKS proxy socks5h://localhost:9050 could not connect to 2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion (0.0.0.0:0) due to: Host unreachable (6) Reading package lists… Done W: Failed to fetch tor+http://5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion/dists/bookworm/updates/InRelease SOCKS proxy socks5h://localhost:9050 could not connect to 5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion (0.0.0.0:0) due to: Host unreachable (6) W: Failed to fetch tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian/dists/bookworm/InRelease SOCKS proxy socks5h://localhost:9050 could not connect to 2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion (0.0.0.0:0) due to: Host unreachable (6) W: Some index files failed to download. They have been ignored, or old ones used instead.
Until the onion service is re-established, complete the following steps in Whonix-Gateway™ (whonix-gateway-17) and Whonix-Workstation™ (whonix-workstation-17) to circumvent the issue. [8] [9]
1. Open Debian sources.list in an editor.
Open file /etc/apt/sources.list.d/debian.list in an editor with root rights.
Non-Qubes-Whonix™
This box uses sudoedit for better security.
sudoedit /etc/apt/sources.list.d/debian.list
Qubes-Whonix™
NOTES:
- When using Qubes-Whonix, this needs to be done inside the Template.
sudoedit /etc/apt/sources.list.d/debian.list
- After applying this change, shutdown the Template.
- All App Qubes based on the Template need to be restarted if they were already running.
- This is a general procedure required for Qubes and unspecific to Qubes-Whonix™.
Others and Alternatives
- This is just an example. Other tools could achieve the same goal.
- If this example does not work for you or if you are not using Whonix, please refer to this link.
sudoedit /etc/apt/sources.list.d/debian.list
2. Comment (#) the .onion address lines and uncomment the clearnet address lines.
The code blocks should look like this; only these entries require editing. [10]
deb tor+https://deb.debian.org/debian bullseye main contrib non-free deb tor+https://deb.debian.org/debian bullseye-updates main contrib non-free deb tor+https://deb.debian.org/debian-security bullseye-security main contrib non-free deb tor+https://deb.debian.org/debian bullseye-backports main contrib non-free deb tor+https://fasttrack.debian.net/debian bullseye-fasttrack main contrib non-free #deb tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian bullseye main contrib non-free #deb tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian bullseye-updates main contrib non-free #deb tor+http://5ajw6aqf3ep7sijnscdzw77t7xq4xjpsy335yb2wiwgouo7yfxtjlmid.onion/debian-security bullseye-security main contrib non-free #deb tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian bullseye-backports main contrib non-free
Save and exit.
3. Confirm the clearnet repositories are functional.
sudo apt update
4. Optional: Revert and update the package lists.
Consider reverting these changes later on because onion repositories have various security advantages. Afterwards, apply Updates to refresh the package lists.
Updating with Extra Care[edit]
See 
How-to: Install or Update with Utmost Caution
.
Footnotes[edit]
- ↑ See: How to update.
- ↑
Quote Andrew David Wong, Community Manager, @QubesOS. CCO, Invisible Things Lab:
3. Selecting a VM in the Qube Manager and pressing the "Update" button. [...]. (3) is a weird in-between method that is inferior to (2). For example, historically, not all of the Salt fixes applied by (2) have been applied by (3), which is a security problem.
- ↑
https://forums.whonix.org/t/cant-update-any-whonixvm-in-qubes-4-0-or-whonixcheck/6023
- ↑ Steps 1 and 2 can be combined with:
upgrade-nonroot. - ↑ Rollback or indefinite freeze attacks as defined by The Update Framework (TUF) - Threat Model - Attacks and Weaknesses - https://theupdateframework.io/security/ -.
- ↑ Or Whonix changes can be delayed, inspected, and then backported if the effort is worth it.
- ↑
Whonix uses package
config-package-dev which assumes ownership of configuration files coming from “other distributions” (mostly Debian, although third party repositories might be added by users). (Whonix on config-package-dev) - ↑ If similar issues occur with Whonix or Qubes onion services then follow the same procedure and modify the
derivative.listandqubes-r4.listfiles, respectively. - ↑ https://forums.whonix.org/t/errors-updating-september-2018/6028
- ↑ There is no Debian onion for fasttrack yet.
The most watertight privacy operating system in the world.
At
Whonix we value freedom and trust, supporting Open Source and Freedom Software
2012-
2024 ENCRYPTED SUPPORT LP
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!