Important! Everything must stay current.
Preparation Step 1) Configure TemplateVM proxy settings
Attach Whonix TemplateVMs to a Whonix-Gateway ProxyVM (commonly called sys-whonix).
Qubes VM Manager ->
right-click on TemplateVM
Repeat this procedure with
Qubes VM Manager ->
right-click on TemplateVM
Preparation Step 2) Open a TemplateVM Terminal
Qubes App Menu(blue/grey "Q") -> Template: whonix-gw -> Konsole
Qubes App Menu(blue/grey "Q") -> Template: whonix-ws -> Konsole
Preparation Step 3.) Note
The following steps should be applied in both TemplateVM terminals.
1. Update the Package Lists
Check package lists on at least a daily basis and keep the host operating system updated. 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 you see something like this.
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.
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 don't proceed! Press man-in-the-middle attack, which isn't 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 it. If not, something is broken or it is a
4. Signature Verification Warnings
There should be no signature verification warnings at the moment. If such a warning appears, 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 isn't 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 isn't 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.
Shutdown Whonix TemplateVM
Qubes VM Manager -> right click on TemplateVM -> Shutdown VM
8. Restart/Update Whonix VMs
If new updates were available and installed, you will need to either simply restart your running Whonix-Gateway ProxyVMs and running Whonix-Workstation AppVMs for them to be updated -- or alternatively apply this same update process again to your running VMs if not wanting to restart them right away.
- 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.
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.