Actions

Install Software


Easy[edit]


A primary Whonix goal is to greatly reduce the risk posed by (additional) software installations that are not exclusively designed to work with Tor.

Users can install any software inside Whonix-Workstation using apt-get, since it is based on Debian. However, this is not a recommendation for installing additional software.

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.

Best Practices[edit]

Prefer APT[edit]

Generally, the safest option is to stick with Debian's official package manager APT. This is referenced throughout the wiki whenever the user runs apt-get. APT is a secure package manager which passes the TUF threat model, since it features metadata verification and expiration detection. [1] [2]

Avoid Third Party Package Managers[edit]

There are many third party package managers besides APT, however they lack the security safeguards that are standard in Debian. Popular examples are pip and node.js. The security concern with third party options is they do not verify the code comes from the author. When used, these package managers will run processes that pull untrusted code from the Internet and perform operations with root level permissions. If a trusted Workstation VM is required for sensitive use cases such as a Bitcoin wallet, then users should completely avoid this option. [3] [4]

Avoid Manual Software Installation[edit]

Generally avoid the manual installation of packages, even trusted ones. In practice that means most users should only be installing software with apt-get, unless special circumstances exist. [5] Another risk is that foreign packages are often unsigned, and users may forget to update the software in a timely fashion.

Prefer Packages from Debian Stable Repository[edit]

Users who decide to install new software after considering the risks should preference Debian's Stable repository, rather than the Testing / Unstable or third party repositories.

The Debian FAQ provides a strong rationale for using the stable repository:

Stable is rock solid. It does not break and has full security support. But it not might have support for the latest hardware.


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.


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.

Mixing packages from Debian testing or Debian unstable should only be attempted by advanced users. The reason is it could lead to a dependency hell, making it very difficult to resolve the breakage of APT package management.

To use newer package versions, Debian backports [6] is a far safer alternative than the Debian testing or unstable repositories. However, Debian backports should be used conservatively:

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!

For instructions on using Debian backports, see here.

GUI Applications with Root Rights[edit]

Never login as root user (sudo su) or run GUI applications using sudo application. This will fail and is a limitation inherited from Debian. If a user attempts this action, error messages like those below will appear.

No protocol specified
cannot connect to X server :0

As a KDE user (Non-Qubes-Whonix default) use kdesudo application. Otherwise, use gksudo application. For example.

Open /etc/tor/torrc in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run.

kdesudo kwrite /etc/tor/torrc

If you are using a terminal-only Whonix, run.

sudo nano /etc/tor/torrc

More Security[edit]

General Advice[edit]

Whonix users are free to install their favorite software packages, but should be aware that additional software increases the attack surface of the platform. [7] Almost any application can be installed, with a few exceptions for programs that are impossible to torify. In addition, Whonix provides:

Users are responsible for trying to prevent any other protocol leaks using the "Torify: How-to" guide, but most of those are mitigated by Whonix.

apt-get Meta-data[edit]

When updating with apt-get, information will leak about which software packages and versions have been installed, unless Tor onion repositories have been configured. [8] 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. [9] [10]

Recommendations[edit]

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[edit]

  1. Stop all activities and shutdown any open applications like Tor Browser.
  2. Change the Tor circuit (this step may not apply if the user is running an onion service). [11]
  3. Update using apt-get after a random delay. By default, a new Tor circuit is generated after 10 seconds.
  4. Change the Tor circuit again.
  5. Continue user activities after another random period has elapsed.

Whonix-Workstation is Firewalled[edit]


The Whonix-Gateway firewall [12] 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. [13]


Also note:


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.

Related:

Advanced[edit]

Backports[edit]

Read #Prefer Packages from Debian Stable Repository first.

1. Boot the Whonix-Workstation (whonix-ws) TemplateVM

2. Add the current Debian stable backports codename jessie-backports to sources.list

Note: this applies to Whonix 13.0.0.1.4. Later Whonix versions may use a codename different to jessie.

In the Whonix-Workstation (whonix-ws) TemplateVM, run.

sudo su -c "echo -e 'deb http://http.debian.net/debian jessie-backports main' > /etc/apt/sources.list.d/backports.list"

Or alternatively use the .onion mirror.

sudo su -c "echo -e 'deb http://vwakviie2ienjx6t.onion/debian jessie-backports main' > /etc/apt/sources.list.d/backports.list"

3. Update the package lists

sudo apt-get update

4. Install the selected software

sudo apt-get -t jessie-backports install packagename

  • Replace packagename with the package you actually want to install.

The procedure is now complete.

5. Undo

On occasion it is necessary to undo this configuration, for example when upgrading from Debian jessie to buster. [20] To proceed, run.

sudo rm /etc/apt/sources.list.d/backports.list

Install from Debian testing[edit]

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 testing 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-debian-testing-mix) due to the risks. Ask for advice in the forums on a case by case basis.

1. Boot the Whonix-Workstation (whonix-ws-debian-testing-mix) TemplateVM

2. Add the current Debian testing codename buster to sources.list

Note: this applies to Whonix 14. Later Whonix versions may use a codename different to buster.

In the Whonix-Workstation (whonix-ws-debian-testing-mix) TemplateVM, run.

sudo su -c "echo -e 'deb http://http.debian.net/debian buster main' > /etc/apt/sources.list.d/testing.list"

Or alternatively use the .onion mirror.

sudo su -c "echo -e 'deb http://vwakviie2ienjx6t.onion/debian buster main' > /etc/apt/sources.list.d/testing.list"

3. Update the package lists

sudo apt-get update

4. Install the selected software

sudo apt-get -t buster install packagename

  • Replace packagename with the package you actually want to install.

The procedure is now complete.

5. Undo

On occasion it is necessary to undo this configuration, for example when upgrading from Debian jessie to buster. [21] To proceed, run.

sudo rm /etc/apt/sources.list.d/testing.list

Package Reinstallation[edit]

As per the free support principle, package reinstallation uses normal Debian processes.

The example below shows how the thunderbird package would be reinstalled. The user can substitute thunderbird with many other packages, so long as they do not have too many dependencies. The instructions are not suitable with any packages that are required for connectivity such as tor, because the reinstallation would be very difficult and is currently unsupported.

Even in the case of the thunderbird package, dependency complications emerge. The anon-workstation-packages-recommended package also depends on thunderbird. Further, the whonix-workstation package depends on anon-workstation-packages-recommended.

Update the package lists and upgrade before starting this procedure. See updates for instructions.

Purge the package you want to reinstall.

sudo apt-get purge thunderbird

The output will show something like the following.

Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following packages will be REMOVED:
  anon-workstation-packages-recommended* thunderbird* whonix-workstation*
0 upgraded, 0 newly installed, 3 to remove and 0 not upgraded.
After this operation, 90.8 MB disk space will be freed.
Do you want to continue? [Y/n] 
(Reading database ... 100681 files and directories currently installed.)
Removing whonix-workstation (3:2.9-1) ...
Removing anon-workstation-packages-recommended (3:2.9-1) ...
Removing thunderbird (38.4.0esr-1~deb8u1) ...
Purging configuration files for thunderbird (38.4.0esr-1~deb8u1) ...
Processing triggers for hicolor-icon-theme (0.13-1) ...
Processing triggers for menu (2.1.47) ...
Processing triggers for man-db (2.7.0.2-5) ...
Processing triggers for desktop-file-utils (0.22-1) ...
Processing triggers for qubes-core-agent (3.0.20-1+deb8u1) ...
Processing triggers for mime-support (3.58) ...

The packages anon-workstation-packages-recommended and whonix-workstation have been inadvertently uninstalled due to technical limitations. [22] These packages will be reinstalled later.

Delete the user configuration folder if that is desired. In this thunderbird example, the user configuration folder would be the following (it differs depending on the package).

rm -r ~/.thunderbird

Now reinstall the thunderbird package and the additional packages that were purged. The --no-install-recommends parameter below is optional.

sudo apt-get install --no-install-recommends thunderbird anon-workstation-packages-recommended whonix-workstation

Related to: Whonix Debian Packages.

Foreign Sources[edit]

In most cases, the extensive software range available from the official Debian repositories should be enough to meet 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. [23]

Risks[edit]

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.

Security Issues[edit]

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. [24]

Dependency Hell[edit]

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.

Mitigation[edit]

Users can reduce security risks and eliminate the risk of making the workstation unusable by using Multiple Whonix-Workstations.

Footnotes[edit]

  1. https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md http://www.webcitation.org/6F7Io2ncN
  2. https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html
  3. https://web.archive.org/web/20170919173146/https://arstechnica.com/information-technology/2017/09/devs-unknowingly-use-malicious-modules-put-into-official-python-repository/
  4. 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.
  5. Such as desirable software versions that are not yet bundled in the official repositories.
  6. Debian Backports
  7. https://en.wikipedia.org/wiki/Attack_surface
  8. See software updaters for more information on this topic.
  9. 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.
  10. 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.
  11. One option is using Arm: Navigate to Whonix-Gateway (Qubes-Whonix: sys-whonix) and select Arm - Tor Controller. Press n for a "New Identity". Alternatively, press m for the menu, scroll down to New Identity and press Enter.
  12. The firewall is found on the Whonix-Gateway: /usr/bin/whonix_firewall
  13. If the DNS server is changed in Whonix-Workstation's /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.
  14. The only missing elements at the time of writing were automatic client connections and inter-relay connections via IPv6. Bridges are fully supported.
  15. https://phabricator.whonix.org/T509
  16. 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.
  17. To preserve the anonymity of a user's Whonix-Workstation activities, it is not necessary to torify Whonix-Gateway's own traffic.
  18. For reader interest: If DNS settings on Whonix-Gateway are changed in /etc/resolv.conf, this only affects Whonix-Gateways'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 Stream Isolation).
  19. Whonix-Workstation's 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 nslookup - will use the default DNS server configured in Whonix-Workstation (via /etc/network/interfaces), which is the Whonix-Gateway. Those DNS requests are redirected to Tor's DnsPort by Whonix-Gateway's firewall. Whonix-Gateway's /etc/resolv.conf does not affect Whonix-Workstation's DNS requests.
  20. Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see stay tuned).
  21. Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see stay tuned).
  22. Whonix_Debian_Packages#Technical_Stuff
  23. https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html
  24. With reproducible package builds on the horizon, the security risk from the second factor will be minimal in the future.

Random News:

Want to make Whonix safer and more usable? We're looking for helping hands. Check out the Open Issues and development forum.


https | (forcing) onion

Share: Twitter | Facebook

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.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)