Install Additional Software Safely
- 1 Easy
- 2 Best Practices
- 3 More Security
- 4 Whonix-Workstation ™ is Firewalled
- 5 Advanced
- 6 Foreign Sources
- 7 Footnotes
Qubes-Whonix ™ users need to install and update persistant software in the Whonix-Workstation ™ TemplateVM(s) (
Using apt-get in the a TemplateBased AppVM (
A primary Whonix ™ goal is to greatly reduce the risk posed by (additional) software installations that are not exclusively designed to work with Tor.
Whonix ™ is currently the most secure platform for running Tor-unsafe applications like Adobe Flash; see the operating system comparison.
The Whonix ™ software page lists:
- Pre-installed Whonix ™ applications which are available for different tasks.
- Recommended software for different user activities.
- Safety advice.
- Installation instructions.
Install from Debian stable
To install a package from Debian stable, follow the steps below. Replace
package-name with the name of the software you want to install.
Update the package lists.
sudo apt-get update
Upgrade the system.
sudo apt-get dist-upgrade
sudo apt-get install package-name
The procedure of installing
package-name is now complete.
There are numerous examples of this procedure in the Software chapter and throughout the wiki.
Table: Best Software Installation Practices
|Avoid Third Party Package Managers||
|Avoid Manual Software Installation||
|Always Verify Signatures||
|Prefer Packages from Debian Stable Repository||
Whonix ™ users are free to install their favorite software packages, but should be aware that additional software increases the attack surface of the platform. Almost any application can be installed, with a few exceptions for programs that are impossible to torify. In addition, Whonix ™ provides:
- Protection from IP and DNS leaks (see above for details).
- Partial protection against protocol leaks and fingerprinting, but this is far from perfect.
When updating with
apt-get, information will leak about which software packages and versions have been installed, unless Tor onion repositories have been configured.  This meta-data cannot be directly linked to any other activity like web browsing, because the Whonix ™ apt-get uwt wrapper forces it to pass through its own circuit. Despite this isolation, it is still possible for updates to be correlated with the same pseudonym.  
For greater security when updating:
- Follow the guidelines below.
- Be especially careful when adding custom repositories, particularly Personal Package Archives (PPAs). Single developers are more easily pressured and/or likely to have malicious intent than the main distribution repositories.
- Read the protocol leak and fingerprinting protection entry first. It highlights useful information, like the fact that DNS and IP-related leaks do not apply to Whonix ™.
- Refer to the Tor Project's Torify: How-to which discusses various protocol leaks and how to mitigate them.
- Review the Tor Project's Transparent Proxy Leaks documentation, which is particularly relevant for Microsoft Windows.
How-to: Install or Update with Utmost Caution
- Stop all activities and shutdown any open applications like Tor Browser.
- Change the Tor circuit (this step may not apply if the user is running an onion service). 
- Update using apt-get after a random delay. By default, a new Tor circuit is generated after 10 seconds.
- Change the Tor circuit again.
- Continue user activities after another random period has elapsed.
Whonix-Workstation ™ is Firewalled
Note: This section is for users interested in server software or other advanced / uncommon applications.
The Whonix-Gateway ™ firewall  has several effects upon the Whonix-Workstation ™:
- Incoming connections are not supported.
- If programs make outgoing connections, then incoming connections are accepted for web browsing, IRC, or other relevant applications.
- Server ports ("open ports") are blocked.
- The Ident Protocol / web server listening port is not reachable, unless it is explicitly configured.
- Onion Services can be hosted.
- Standard DNS requests on UDP port 53 are redirected to Tor's DnsPort. 
- Tor does not support UDP. This is not a Whonix ™-specific issue.
- Tor only partially supports IPv6, although full implementation is likely in the near term.  This is not a Whonix ™-specific issue. 
- All traffic from Whonix-Workstation ™ and Whonix-Gateway ™ is routed over Tor.     Users should read the footnotes on the left-hand side.
The firewall on the Whonix-Gateway ™ is very restrictive. It can be made even more restrictive by activating #OptionalFeatureNr.3# within the firewall script. It is possible to limit which outgoing ports are redirected to Tor's TransPort. Depending on what the user is trying to achieve, it could also be useful to remove all SocksPorts.
Install from Debian Testing
Mixing packages from Debian
Before completing steps in this section, first read Prefer Packages from Debian Stable Repository. Carefully check how packages will change before proceeding -- a host of upgrades is usually safe, but no Whonix ™ packages should be removed as part of the process; see Whonix Debian Packages. Be aware that problems are still possible - see here for an example.
It is recommended to complete this process in a separate Whonix-Workstation ™ (
whonix-ws-14-debian-testing-mix) due to the risks. Ask for advice in the forums on a case-by-case basis.
Install from Debian Unstable
Managing security updates for the "stable" distribution remains the hightest priority for the Debian security team. This means security-fixes for Debian "unstable" are managed by the maintainers themselves and not not by the Debian security team. Therefore, "unstable" does not receive security updates in a timely manner. 
Before completing steps in this section, first read Prefer Packages from Debian Stable Repository.
Mixing packages from Debian
stable with those from a later release like
unstable can destabilize the system due to associated software dependencies required for full functionality. First carefully check how packages will change before proceeding  -- a host of upgrades is usually safe, but no Whonix ™ packages should be removed as part of the process; see Whonix Debian Packages. It is recommended to complete this process in a separate Whonix-Workstation ™ (
whonix-ws-14-debian-unstable-mix) due to the risks. Ask for advice in the forums on a case-by-case basis.
As per the free support principle, package reinstallation utilizes normal Debian processes.
The example below shows how the thunderbird package would be reinstalled. It is possible to substitute thunderbird with many other packages, so long as they do not have too many dependencies. These instructions are not suitable for any packages needed for connectivity such as tor, because the reinstallation would be very difficult and is currently unsupported.
Even in the thunderbird package example, dependency complications emerge. The anon-workstation-packages-recommended package also depends on thunderbird. Further, the whonix-workstation package depends on anon-workstation-packages-recommended.
Install Software in a TemplateBasedVM
Qubes-Whonix ™ only! Custom scripting is recommended, which is beyond the scope of this entry. Numerous free articles and instructions can be easily found with a search engine.
There is no reason to avoid installing software in TemplateBasedVMs, although software installed this way will not persist across reboots. Users can opt to use a custom script to automate this process, thereby minimizing time spent re-installing packages.
- Centralized Updates: AppVMs are based on a TemplateVM. This means the AppVM's root filesystem is based on the corresponding template's root filesystem. Users need only update the TemplateVM and those updates will be reflected in the TemplateBasedVM's root filesystem upon restart.
- Minimal Disk Usage: TemplateBasedVMs require much less disk space than StandaloneVMs, since the AppVM's root filesystem is based the corresponding template. The AppVM only requires enough disk space to hold user files in the
- Semi-persistent Storage: User data stored in
/usr/localsurvives reboot. Many applications like Signal and Wire store user data in the
/homefolder. Since the custom script installs the software seamlessly with little or no user interaction, the AppVM has "quasi-full persistence", not unlike a StandaloneVM's full persistence.
Once user preparation is complete and the AppVM is started, it will automatically start the script to begin installing software. When the process finishes, the AppVM can be used like any other TemplateBasedVM. However when the AppVM is shutdown, all data outside of the persistent
/home folder will be lost, including the newly installed software packages. Following reboot, the VM will again install the software packages automatically.
Using bind-dirs Selective Persistence
Using selective bind-dirs persistence is currently a difficult problem and undocumented. Further research is required to ascertain which files require persistence across VM reboots.
Add Application Launcher to Start Menu
mkdir -p ~/.local/share/applications
Create a new file
~/.local/share/applications/program-name.desktop using an editor.
Paste the following contents.
[Desktop Entry] Type=Application Exec=/path/to/program Name=program-name Categories=Other
The procedure is now complete.
You can find the launcher here:
Start Menu ->
In most cases, the extensive software range available from the official Debian repositories should be enough to satisfy the user's needs. A selection of more than 50,000 programs can be installed within a couple of steps. These packages are constantly maintained for bug/security fixes and tightly integrated to provide a stable distribution.
To guarantee stability, no new versions are uploaded to Debian stable archives to avoid breaking the system. This makes Debian stable a dependable distribution and an excellent base for downstream distributions. However, the Linux software scene is very dynamic and sometimes the user will want software that is not yet packaged in Debian. In this instance, it may be necessary to install software from separate sources; either from third party repositories, as a stand-alone precompiled .deb binary, or directly compiled source packages. 
The use of foreign sources should be kept to a minimum, as it may cause problems. Note this is simply a warning about the worst case scenario and not a predetermined outcome of installing third party software.
Keep in mind that foreign sources pose important security implications for the user's system. Installing software is tantamount to granting root privileges to the developers. Software originating from dubious sources could replace important system components with malicious versions that allow backdoors or Trojan horses to be installed on the system.
In general, the installation of software is a matter of trust. The fact is that users have to trust every software source they install. This trust is two-fold: firstly that the developers have integrity, and secondly that the community will notice any suspicious code, which might indicate compromise of the developers' machines. 
Manually installed packages can contain library versions not available in the standard repositories. This causes problems with dependency resolution when installing additional software from the official repository. Individual applications are less critical in this context, but when important system libraries in the third-party software are considered, complications are inevitable.
Depending on the severity of the complications, upgrades to the next version of the operating system might fail, or the system may become unbootable or generally unstable.
- https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md http://www.webcitation.org/6F7Io2ncN
- The pip developers refused to implement any kind of proper GPG signature verification, opting to support server HTTPS instead which is a lot weaker. While the TUF secure updater project has implemented a safe version of pip, it is not clear how widely it has been adopted and whether it will become popular.
- Such as desirable software versions that are not yet bundled in the official repositories.
If security or stability are at all important for you: install stable. period. This is the most preferred way.
Since there is typically over 1 year between releases you might find that stable contains old versions of packages. However, they have been tested in and out. One can confidently say that the packages do not have any known severe bugs, security holes etc., in them. The packages in stable integrate seamlessly with other stable packages. These characteristics are very important for production servers which have to work 24 hours a day, 7 days a week.
Stable is rock solid. It does not break and has full security support. But it might not have support for the latest hardware.
On the other hand, packages in testing or unstable can have hidden bugs, security holes etc. Moreover, some packages in testing and unstable might not be working as intended.
- Debian Backports: "Backports are packages taken from the next Debian release (called "testing"), adjusted and recompiled for usage on Debian stable."
Backports cannot be tested as extensively as Debian stable, and backports are provided on an as-is basis, with risk of incompatibilities with other components in Debian stable. Use with care!
- See software updaters for more information on this topic.
- Consider the following example. A user announces online that software X is being utilized, and another specific application set x, y, and z is installed. If this information becomes available to an adversary and the circuit-isolated apt-get passes through any Tor exit relays, mirrors or ISPs under their control, then they may guess it is associated with the same pseudonym. In that case, the adversary has a list of the user's installed packages, and can attempt a stale mirror attack (if the user has a custom Ubuntu build), or try other attacks against apt-get.
- As per the previous footnote, this threat equally applies to users who run an onion service with a specific set of server software, for example apache, mediawiki, phpbb, and others.
- One option is using Arm: Navigate to Whonix-Gateway ™ (Qubes-Whonix ™:
sys-whonix) and select
Arm - Tor Controller. Press
nfor a "New Identity". Alternatively, press
mfor the menu, scroll down to New Identity and press
- The firewall is found on the Whonix-Gateway ™: /usr/bin/whonix_firewall
- If the DNS server is changed in Whonix-Workstation ™ /etc/resolv.conf, this will likely have no effect. The reason is the firewall on Whonix-Gateway ™ will redirect all those requests to Tor's DnsPort. The working exception to this rule is when users tunnel / encrypt DNS requests (DNSCrypt, httpsdnsd), as per the secondary DNS resolver instructions.
- The only missing elements at the time of writing were automatic client connections and inter-relay connections via IPv6. Bridges are fully supported. See also: IPv6 roadmap.
- Since Whonix 0.2.1, Whonix-Gateway ™ traffic is also routed over Tor. In this way, use of Whonix is hidden from persons or systems observing the network.
- To preserve the anonymity of a user's Whonix-Workstation ™ activities, it is not necessary to torify Whonix-Gateway ™ own traffic.
- For reader interest: If DNS settings on Whonix-Gateway ™ are changed in Stream Isolation). , this only affects Whonix-Gateway ™s's own DNS requests issued by applications using the system's default DNS resolver. By default, no applications issuing network traffic on Whonix-Gateway ™ use the system's default DNS resolver. All applications installed by default on Whonix-Gateway ™ that issue network traffic (apt-get, whonixcheck, timesync) are explicitly configured, or forced by uwt wrappers, to use their own Tor SocksPort (see
- Whonix-Workstation ™ default applications are configured to use separate Tor SocksPorts (see Stream Isolation), thereby not using the system's default DNS resolver. Any applications in Whonix-Workstation ™ that are not configured for stream isolation - for example - will use the default DNS server configured in Whonix-Workstation ™ (via ), which is the Whonix-Gateway ™. Those DNS requests are redirected to Tor's DnsPort by Whonix-Gateway ™ firewall. Whonix-Gateway ™ does not affect Whonix-Workstation ™ DNS requests.
- Users should Prefer Packages from Debian Stable Repository, but using backports is better than manual software installation or using third party package managers since this prefers APT. To contain the risk, Non-Qubes-Whonix ™ users might want to consider using Multiple Whonix-Workstation ™ and Qubes-Whonix ™ users might want to consider using Multiple Qubes-Whonix ™ TemplateVMs or Software Installation in a TemplateBasedVM.
- Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
- Most often this step applies before attempting major Whonix ™ upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
- See: https://wiki.debian.org/DebianUnstable#What_are_some_best_practices_for_testing.2Fsid_users.3F
- It is recommended to create aMultiple Whonix-Workstation ™ to install the package due to these risks.
- Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see stay tuned).
- Qubes install software
- Obvious hook targets include .bashrc, the Firefox profile directory (which contains extensions), or PDF or DOC documents that are likely to be opened by the user.
- With reproducible package builds on the horizon, the security risk from the second factor will be minimal in the future.
No user support in comments. See Support.
Comments will be deleted after some time. Specifically after comments have been addressed in form of wiki enhancements. See Wiki Comments Policy.
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.
Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)