Operating System Software and Updates
Users should not run software that has reached end-of-life status, because developers will not fix existing defects, bugs or vulnerabilities, posing serious security risks.
A recent example was VLC in Debian jessie, which reached end-of-life status in May, 2018. In that case, Whonix 13 users who did not utilize a different media player were at risk, because VLC in jessie has unpatched security vulnerabilities. This VLC vulnerability does not apply to the current stable Whonix 14 release.
Installing Additional Software
See Install Software.
All packages must stay up-to-date for security and anonymity purposes.
- Qubes Whonix: Follow the Qubes-Whonix Update Guide.
- All other Whonix OS builds: Follow the update instructions below.
Standard Upgrade vs Release Upgrade
This procedure is for every day upgrading of Non-Qubes-Whonix and will not perform a Release Upgrade.
If a message like this appears.
WARNING: Whonix News Result:
✘ Outdated: Installed whonix-gateway-packages-dependencies 3.4.2-1 is outdated!
WARNING: Whonix News Result:
✘ Outdated: Installed whonix-workstation-packages-dependencies 3.4.2-1 is outdated!
Then most likely a Release Upgrade is necessary.
Before applying a release upgrade, it is useful to first complete a standard upgrade as documented below.
Standard Upgrade Steps
1. Update the Package Lists
At least once a day users should update the system package lists  with the latest version information on new and updated packages that are available for download. To update Whonix-Gateway and Whonix-Workstation packages lists, run.
sudo apt-get update
The output should look similar to this.
Hit http://security.debian.org stretch/updates Release.gpg Hit http://security.debian.org stretch/updates Release Hit http://deb.torproject.org stretch Release.gpg Hit http://ftp.us.debian.org stretch Release.gpg Hit http://security.debian.org stretch/updates/main amd64 Packages Hit http://deb.torproject.org stretch Release Hit http://security.debian.org stretch/updates/contrib amd64 Packages Hit http://ftp.us.debian.org stretch Release Hit http://security.debian.org stretch/updates/non-free amd64 Packages Hit http://deb.torproject.org stretch/main amd64 Packages Hit http://security.debian.org stretch/updates/contrib Translation-en Hit http://ftp.us.debian.org stretch/main amd64 Packages Hit http://security.debian.org stretch/updates/main Translation-en Hit http://ftp.us.debian.org stretch/contrib amd64 Packages Hit http://security.debian.org stretch/updates/non-free Translation-en Hit http://ftp.us.debian.org stretch/non-free amd64 Packages Ign http://ftp.us.debian.org stretch/contrib Translation-en Ign http://ftp.us.debian.org stretch/main Translation-en Ign http://ftp.us.debian.org stretch/non-free Translation-en Ign http://deb.torproject.org stretch/main Translation-en_US Ign http://deb.torproject.org stretch/main Translation-en Reading package lists... Done
If an error message like this appears.
W: Failed to fetch http://ftp.us.debian.org/debian/dist/stretch/contrib/binary-amd64/Packages 404 Not Found W: Failed to fetch http://ftp.us.debian.org/debian/dist/stretch/non-free/binary-amd64/Packages 404 Not Found E: Some index files failed to download. They have been ignored, or old ones used instead. Err http://ftp.us.debian.org stretch Release.gpg Could not resolve 'ftp.us.debian.org' Err http://deb.torproject.org stretch Release.gpg Could not resolve 'deb.torproject.org' Err http://security.debian.org stretch/updates Release.gpg Could not resolve 'security.debian.org' Reading package lists... Done W: Failed to fetch http://security.debian.org/dists/stretch/updates/Release.gpg Could not resolve 'security.debian.org' W: Failed to fetch http://ftp.us.debian.org/debian/dists/stretch/Release.gpg Could not resolve 'ftp.us.debian.org' W: Failed to fetch http://deb.torproject.org/torproject.org/dists/stretch/Release.gpg Could not resolve 'deb.torproject.org' W: Some index files failed to download. They have been ignored, or old ones used instead.
500 Unable to connect
Then something went wrong. It could be a temporary Tor exit relay or server failure that should resolve itself. Check if the network connection is functional by changing the Tor circuit and trying again. Running whonixcheck might also help to diagnose the problem.
Sometimes a message like this will appear.
Could not resolve 'security.debian.org'
It that case, it helps to run.
And then try again.
To install the newest versions of the current packages installed on the system, run.
sudo apt-get dist-upgrade
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 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.and . Running again should fix the problem. If not, something is broken or it is a
4. Signature Verification Warnings
There should be no signature verification warnings at present. If such a warning occurs, it will look like this.
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://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-get will automatically ignore repositories with expired keys or signatures, and the user will not receive upgrades from that repository. Unless the issue is already known or documented, it should be reported so it can be further investigated.
There are two possible reasons why this could happen. Either there is an issue with the repository that the maintainers have yet to fix or the user is the victim of a man-in-the-middle attack.  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 see how the documentation looked 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: http://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 W: Failed to fetch http://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.
Please report any other signature verification errors if/when they appear. This outcome is considered unlikely at this time.
5. Changed Configuration Files
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 maintainer'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
Be careful. If the updated file is not coming from a Whonix specific package (some are called), then press . Otherwise, Whonix settings affecting anonymity, privacy, and security might be lost. Advanced users who know better can of course manually check the differences and merge them.
This is how to determine if the file is coming from a Whonix-specific package or not:
- Whonix-specific packages are sometimes called Setting up ifupdown ...", so the file is not coming from a Whonix-specific package. In this case, the user should press as previously advised. . In the example above it is saying "
- If the package name does include Whonix's modular flexible .d style configuration folders. , it is a Whonix-specific package. In that case, the safest bet is pressing , but then any customized settings will be lost (these can be re-added afterwards). Such conflicts will hopefully rarely happen if using
6. Restart Services After Upgrading
To restart services after upgrading, either simply reboot.
Or to omit rebooting, use the needrestart method (harder). For users interested in the latter method, please click on Expand on the right side.
Do this once. Install needrestart.
sudo apt-get update sudo apt-get install needrestart
The program will provide some advice. Run it again after applying the advice.
If nothing else has to be restarted, it should show.
No services need to be restarted.
This feature might become more usable and automated in the future. (T324)
7. Restart After Kernel Upgrades
When linux-image-... is upgraded, a reboot is required to profit from any security updates.
Non-functional Onion Services
Occasionally the Debian onion servers are non-functional, meaning users cannot complete updates automatically. In that case, an error message like the following will appear.
user@host:~$ sudo apt-get update && sudo apt-get dist-upgrade Hit:1 http://security.debian.org stretch/updates InRelease Hit:2 tor+http://deb.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion stretch InRelease Ign:3 http://ftp.us.debian.org/debian stretch InRelease Hit:4 http://deb.whonix.org stretch InRelease Hit:5 http://ftp.us.debian.org/debian stretch Release Err:7 tor+http://sgvtcaew4bxjd7ln.onion stretch/updates InRelease SOCKS proxy socks5h://localhost:9050 could not connect to sgvtcaew4bxjd7ln.onion (0.0.0.0:0) due to: Host unreachable (6) Err:8 tor+http://vwakviie2ienjx6t.onion/debian stretch InRelease SOCKS proxy socks5h://localhost:9050 could not connect to vwakviie2ienjx6t.onion (0.0.0.0:0) due to: Host unreachable (6) Reading package lists… Done W: Failed to fetch tor+http://sgvtcaew4bxjd7ln.onion/dists/stretch/updates/InRelease SOCKS proxy socks5h://localhost:9050 could not connect to sgvtcaew4bxjd7ln.onion (0.0.0.0:0) due to: Host unreachable (6) W: Failed to fetch tor+http://vwakviie2ienjx6t.onion/debian/dists/stretch/InRelease SOCKS proxy socks5h://localhost:9050 could not connect to vwakviie2ienjx6t.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.
1. Open Debian sources.list in an editor.
Open /etc/apt/sources.list.d/debian.list in an editor with root rights.
2. Comment (#) the lines with the .onion address and uncomment the lines with the clearnet address.
The first two code blocks should look like this. Note: only blocks shown need to be edited.
#deb tor+http://sgvtcaew4bxjd7ln.onion stretch/updates main contrib non-free deb http://security.debian.org stretch/updates main contrib non-free #deb tor+http://vwakviie2ienjx6t.onion/debian stretch main contrib non-free deb http://ftp.us.debian.org/debian stretch main contrib non-free
Save and exit.
3. Confirm the clearnet repositories are functional.
sudo apt-get update
4. Revert and update the package lists.
It is recommended that these changes are reverted at a later time, so users benefit from the security advantages of onion repositories. Afterwards, apply Updates to refresh the package lists.
Updating with Extra Care
- In Whonix and on the host.
- Rollback or indefinite freeze attacks as defined by The Update Framework (TUF) - Threat Model - Attacks and Weaknesses - https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md - http://www.webcitation.org/6F7Io2ncN.
- If similar problems are experienced with Whonix or Qubes onion services then the same procedure can be used to modify the
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.