Easy[edit]

Introduction[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, since it is based on Debian. However, this is not a recommendation for installing additional software. Also, Whonix ™ is currently the most secure platform for running Tor-unsafe applications like the former Adobe Flash plugin (now deprecated); 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[edit]

To install a package from Debian stable, follow the steps below. Replace package-name with the name of the software to be installed.

sudo apt update

sudo apt full-upgrade

sudo apt install --no-install-recommends package-name

There are numerous examples of this procedure in the Software chapter and throughout the wiki.

Best Practices[edit]

Table: Best Software Installation Practices

--no-install-recommends[edit]

Debian's installation default is --install-recommends. Debian packages have various metadata fields such as:

• Depends: dependencies or dependency packages
• Recommends: "recommended" packages
• Suggests: "suggested" packages

When installing a package using apt, dependencies (Depends:) are always installed. The Debian default is for recommended packages (Recommends:) to also be installed alongside the primary package (unless installed previously). To avoid that outcome, it is possible to use the apt command line parameter --no-install-recommends; this is in most cases optional.

Debian's default for suggested packages (Suggests:) is --no-install-suggests i.e. not to install suggested packages. Users can optionally use --install-suggests, but there are no known cases where this would be useful at the time of writing. A host of other command line options ^[archive] are also available.

If a package is installed using apt --no-install-recommends install package-name, then re-running apt without any parameters or even with --install-recommends will not result in installation of the recommended packages. To accomplish a "late" installation of recommended packages, the simplest method is first uninstalling the package. Alternatively, the list of Recommends: can be viewed using apt-cache package-name or by checking the package on https://packages.debian.org ^[archive].

A brief Q&A regarding the potential impacts of the "recommended" field is outlined below.

Table: --no-install-recommends Impacts

Whonix ™ documentation uses --no-install-recommends whenever appropriate. In general, whether users should use --no-install-recommends for package installation is unspecific to Whonix ™ and should be resolved as per Free Support Principle.

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 ^[archive] of the platform. Almost any application can be installed, with a few exceptions for programs that are impossible to torify ^[archive]. 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

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

APT Meta-data[edit]

When updating with apt, information will leak about which software packages and versions have been installed, unless Tor onion repositories have been configured. ^[12] This meta-data cannot be directly linked to any other activity like web browsing, because the Whonix ™ apt 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. ^{[13] [14]}

Recommendations[edit]

For greater security when updating:

• Follow the guidelines below.
• Be especially careful when adding custom repositories, particularly Personal Package Archives (PPAs).^[15] Compared to main distribution repositories, solo developers are more susceptible to influence and theoretically might have malicious intent.
• 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 ^[archive] which discusses various protocol leaks ^[archive] and how to mitigate them.
• Review the Tor Project's Transparent Proxy Leaks ^[archive] 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. ^[16]
3. Update using apt 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 ^[17] has several effects upon Whonix-Workstation ™.

Table: Whonix-Gateway ™ Firewall Effects

Related topics:

• Whonix-Gateway ™ Firewall
• Whonix-Workstation ™ Firewall
• Ports

Advanced[edit]

Install Newer Software Versions[edit]

It is sometimes possible to install newer versions of software applications, either via available backports or by manual installation. When intending to use newer versions of certain applications like Electrum or Monero it is best to approach the process as an application installation, rather than an application update.

In oversimplified terms, a Debian package is just a vehicle to place files into a location. For example, the binaries-freedom Debian package ^[archive] in Whonix ™ ships Electrum. It comes with the appimage file (/usr/share/binaries-freedom/electrum-appimage/electrum-4.0.7-x86_64.AppImage) and a start menu entry (/usr/share/applications/electrum-appimage.desktop). The presence of these files does not impose limitations; it is still possible to customize the system and install newer software versions.

These files can also be ignored; for example it is not necessary to use the electrum-appimage start menu entry. The binaries-freedom package is intended to improve usability and it was never designed to limit customization, nor does it have that side effect. As per Whonix ™ policy there are No Intentional User Freedom Restrictions. ^[29]

As an illustration, a newer version of Electrum would require:

1. uninstalling binaries-freedom (electrum appimage)
2. installing Electrum appimage

To install other custom software, it is suggested to follow recommendations throughout this chapter for better security. Specific instructions for custom software installations will vary for each application. This process is mostly unspecific to Whonix ™ and therefore the Free Support Principle applies to installation steps. The same is true for Qubes-Whonix ™ users -- first consider how this process would be achieved in a Debian-based Qubes template.

Enable Debian Backports Repository[edit]

Operating System Specific Notes:

• Whonix ™ VM users: Should skip this step! Debian APT backports repository is already default in Whonix ™ version 16 and above.
• Debian: The following instructions are for Debian host operating system or Debian VM users.

1. Boot the virtual machine. (Qubes: debian-11 Template).

2. Add the current Debian stable backports codename bullseye-backports to Debian apt sources.

Notes:

• This applies to Debian 16. Later Debian versions will use a codename different to bullseye.
• Advanced users note: Instructions for torification of the fasttrack clearnet repository or fasttrack onion repository can be found in the following footnote.

Run. ^[30]

sudo su -c "echo -e 'deb https://deb.debian.org/debian bullseye-backports main contrib non-free' > /etc/apt/sources.list.d/backports.list"

3. Done.

The procedure of enabling Debian backports repository has been completed.

4. Undo.

On occasion it is necessary to undo this configuration, for example when upgrading from Debian bullseye to bookworm. ^[31] To proceed, run.

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

Enable Debian Fasttrack Repository[edit]

Operating System Specific Notes:

• Whonix ™ VM users: Should skip this step! Debian APT fasttrack repository is already default in Whonix ™ version 16 and above.
• Debian: The following instructions are for Debian host operating system or Debian VM users.

1. Boot the Debian VM. (Qubes: debian-11) Template.

2. Install the fasttrack-archive-keyring package.

sudo apt update

sudo apt full-upgrade

sudo apt install --no-install-recommends fasttrack-archive-keyring

3. Add the current Debian fasttrack APT repository.

Notes:

• This applies to Debian 16. Later Debian versions will use a codename different to bullseye.
• Advanced users note: Instructions for torification of the fasttrack clearnet repository or fasttrack onion repository can be found in the following footnote.

Run. ^[32]

sudo su -c "echo -e 'deb https://fasttrack.debian.net/debian/ bullseye-fasttrack main contrib non-free' > /etc/apt/sources.list.d/fasttrack.list"

4. Done.

The procedure of enabling Debian fasttrack repository has been completed.

5. Undo.

On occasion it is necessary to undo this configuration, for example when upgrading from Debian bullseye to bookworm. ^[33] To proceed, run.

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

Backports[edit]

Debian Backports ^[archive]:

Backports are packages taken from the next Debian release (called "testing"), adjusted and recompiled for usage on Debian stable.

This 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!

sudo apt update

sudo apt -t bullseye-backports install package-name

Fasttrack[edit]

Debian Fasttrack ^[archive]:

Debian Fast Track is a repository that allows making “backports” of packages available to users of the stable distribution, if those packages cannot be maintained in testing and backported in the usual way.

This is a far safer alternative than the Debian testing or unstable repositories. However, Debian fasttrack should be used conservatively similarly to Backports.

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!

sudo apt update

sudo apt -t bullseye-fasttrack install package-name

Install from Debian Testing[edit]

Warnings[edit]

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 ^[archive] for an example.

It is recommended to complete this process in a separate Whonix-Workstation ™ (whonix-ws-16-debian-testing-mix) due to the risks. Ask for advice in the forums on a case-by-case basis.

Procedure[edit]

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

sudo su -c "echo -e 'deb tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian bookworm main' > /etc/apt/sources.list.d/testing.list"

sudo apt update

sudo apt -t bookworm install packagename

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

Install from Debian Unstable[edit]

Warnings[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 unstable can destabilize the system due to associated software dependencies required for full functionality. First carefully check how packages will change before proceeding. ^[38]

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

Procedure[edit]

sudo su -c "echo -e 'APT::Default-Release bullseye;' > /etc/apt/apt.conf.d/70defaultrelease"

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

sudo su -c "echo -e 'deb tor+http://2s4yqjx5ul6okpp3f2gaunr2syex5jgbfpfvhxxbbjwnrsvbk5v3qbid.onion/debian sid main' > /etc/apt/sources.list.d/unstable.list"

sudo apt update

sudo apt install package-name/sid

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

sudo rm /etc/apt/apt.conf.d/70defaultrelease

Package Reinstallation[edit]

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. In the example below the qubes-whonix-workstation-packages-recommended package also depends on thunderbird. Further, the qubes-whonix-workstation package depends on qubes-whonix-workstation-packages-recommended.

sudo apt purge thunderbird

The following packages will be REMOVED:
  qubes-thunderbird* qubes-whonix-workstation*
  qubes-whonix-workstation-packages-recommended* thunderbird*
0 upgraded, 0 newly installed, 4 to remove and 0 not upgraded.
After this operation, 192 MB disk space will be freed.
Do you want to continue? [Y/n] 
(Reading database ... 64719 files and directories currently installed.)
Removing qubes-whonix-workstation (3:21.5-1) ...
Removing qubes-whonix-workstation-packages-recommended (1:16.5-1) ...
Removing qubes-thunderbird (2.0.6-1+deb10u1) ...
Removing thunderbird (1:78.14.0-1~deb10u1) ...
Processing triggers for mime-support (3.62) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...
Processing triggers for man-db (2.8.5-2) ...
Processing triggers for qubes-core-agent (4.0.62-1+deb10u1) ...
Processing triggers for desktop-file-utils (0.23-4) ...
(Reading database ... 64597 files and directories currently installed.)
Purging configuration files for thunderbird (1:78.14.0-1~deb10u1) ...

rm -r ~/.thunderbird

sudo apt install --no-install-recommends thunderbird qubes-whonix-workstation-packages-recommended qubes-whonix-workstation

Install Software in an App Qube[edit]

There is no reason to avoid installing software in App Qubes ^[archive], although installed software will not persist across reboots. A custom script can be used to automate this process, which minimizes the time spent re-installing packages.

Advantages[edit]

This software installation method means a single VM ^[archive] assumes many of the positive characteristics found in both App Qubes and Standalones ^[archive].

• Centralized Updates: App Qubes ^[archive] are based on a Template ^[archive]. This means the App Qube's root filesystem is based on the corresponding template's root filesystem. Any updates to the Template will be reflected in the App Qube's root filesystem upon restart. ^[42]
• Minimal Disk Usage: App Qubes require much less disk space than Standalones, since the App Qube's root filesystem is based on the corresponding template. The App Qube only needs enough disk space to hold user files in the /home directory.
• Semi-persistent Storage: User data stored in /home , /rw and /usr/local survives reboot. Many applications like Signal ^[archive] and Wire ^[archive] store user data in the /home folder. Since the custom script installs the software seamlessly with little or no user interaction, the App Qube has "quasi-full persistence", not unlike a Standalone's full persistence.

App Qube Preparation[edit]

App Qube Use[edit]

Once user preparation is complete and the App Qube has started, it will automatically start the script to begin installing software. When the process finishes, the App Qube can be used like any other. However when the App Qube 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[edit]

Using selective bind-dirs ^[archive] 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[edit]

mkdir -p ~/.local/share/applications

mousepad ~/.local/share/applications/program-name.desktop

[Desktop Entry]
Type=Application
Exec=/path/to/program
Name=program-name
Categories=Other

snap[edit]

General forum discussion about snap: Snap Store / snaps / snapd / snapcraft.io - a new software source? ^[archive]

Qubes-Whonix ™ issues:

• Efforts to persistently install snap apps in Qubes-Whonix ™ via bind-dirs ^[archive] or with snap proxy settings have been unsuccessful. This means it must be installed in an App Qube on every occasion it is required. Efforts to improve this situation are most welcome, see: Wickr Me vs Qubes-Whonix Persistence ^[archive] and snap totally unusable on Qubes whonix-ws ^[archive].
• Qubes Templates are non-networked by default, ^[45] which means snap does not run inside whonix-ws-16 Template. It is likely snap is similarly affected in other Qubes' Templates like the Debian Template. As per Free Support Principle it is recommended to test snap functionality in a non-Whonix based Template before attempting the same procedure inside Whonix ™.

Flatpak[edit]

Introduction[edit]

Flatpak ^[archive] is: ^[46]

...a utility for software deployment and package management for Linux. It is advertised as offering a sandbox environment in which users can run application software in isolation from the rest of the system. ...

Applications using Flatpak need permissions to have access to resources such as Bluetooth, sound (with PulseAudio), network, and files. These permissions are defined by the maintainer of the Flatpak and can be added or removed by users on their system.

Another key feature of Flatpak is that it allows application developers to directly provide updates to users without going through distributions, and without having to package and test the application separately for each distribution.

There are several advantages of utilizing Flatpak: ^{[47] [48] [49]}

• Packages are easily added via Flathub, which is a repository located at flathub.org; for a Whonix ™ example, see here.
• Numerous Linux distributions are either supported out-of-the-box or after the flatpak package is installed; Debian is a supported platform (which Whonix ™ is based upon).
• Desktop applications are sandboxed and have limited access to the host environment. ^[50]
• Flatpak bundles are a single-file format which contains the application or runtime. ^[51]
• Any Flatpak breakage will not lead to destabilization of the host OS.
• Elevated privileges (root) are not required to install Flatpak packages.
• Only changed files are downloaded for updates.
• Libraries and files used by multiple applications are de-duplicated to save space.

For further information, refer to the Flatpak FAQ ^[archive] and Flatpak documentation ^[archive].

Flatpak Package Manager Security[edit]

This entry compares Flatpak security features (such as signed metadata) against Debian's APT package manager. ^[52] With one caveat, Flatpak package manager security is comparable to Debian's APT package manager: Flatpak currently does not defend against indefinite freeze attacks ^[archive].

A definition of indefinite freeze attacks is provided by TUF (The Update Framework) Threat Model ^[archive]:

An attacker continues to present files to a software update system files that the client has already seen. As a result, the client is kept unaware of new files.

For many adversaries this attack is difficult because it requires breaking TLS. While Flatpak package version information is not protected by a valid-until field ^[archive], it is fetched over TLS. Adversaries capable of breaking TLS face an obstacle when dealing with torified connections (like those in Whonix ™) -- an indefinite freeze attack cannot target a specific user, but will affect all Tor users. This increases the chances of being caught unless they also have the ability to break Tor. Even then the attack chain would be very complex:

• Break Tor → Target specific user(s) → Break TLS → Mount an indefinite freeze attack → Exploit a vulnerability caused by an outdated software version.

To safeguard against this possibility, it is recommended to perform manual checks of version numbers for Flatpak-installed applications -- they should match those available from the flathub repository. Every flathub application has a corresponding website page with an Additional information section that lists Updated and Version information. For example, at the time of writing for Chromium:

• This is the associated org.chromium.Chromium flathub website page ^[archive].
• The additional information section lists:
  • Updated: October 5, 2021
  • Version: 94.0.4606.71

Researching version information on the flathub website with a browser is equally vulnerable to indefinite freeze attacks because it also relies upon TLS. It is therefore recommended to use Whonix ™ or Tor Browser for this purpose. ^[53]

Sometimes APT software versions are quite old, which can lead to less functionality or even exposure to known vulnerabilities that are being exploited in the wild (see footnote). ^[54] Conversely, Flatpak usually offers more recent software versions and/or deploys security fixes in a more timely manner.

In summary, Flatpak advantages are considered to outweigh the potential risks of an indefinite freeze attack because the attack chain is complex. Also, Flatpak is sometimes the only trustworthy, easy-to-use software source that provides newer versions than available in Debian stable (with Frozen Packages) (or newer).

Forum discussion:

• flathub as a source of software ^[archive].

Flatpak Sandbox Security[edit]

Flatpak's sandbox is imperfect. Despite Flatpak sandbox issues, it is safe to use in the software installation context. By comparison, Debian's default package manager APT does not attempt to sandbox applications it is running at all.

Flatpak is a victim of imperfect marketing. Since the Flatpak sandbox is a built-in feature, any reported security issues reflect negatively on Flatpak's reputation. Frequently, non-technical users are unable to properly contextualize or assert its impact through threat modeling. Building a "perfect" sandbox is a much harder task -- containing arbitrary, ever-changing applications running on an ever-changing operating system -- than creating a package manager. The latter is essentially a file delivery mechanism and is therefore comparatively simpler to develop.

Flatpak sandboxing abilities are irrelevant so long as the sandboxing is not worse than software that is manually installed. Whatever Flatpak's sandbox is doing, it should not break an application’s own sandboxing. ^[55]

Flatpak's own sandboxing capabilities interfere with other sandboxing initiatives like Sandboxed Application Launcher and Firejail: ^[56]

Is Flatpak compatible with other desktop isolation frameworks? In general unprivileged container systems can’t stack, because anything running inside the sandbox does not have the necessary privileges to set up a sandbox, nor does it have the ability to raise its privileges in any way. For instance, Firejail can never work inside Flatpak, because it is setuid. That being said, using multiple sandboxing frameworks at once does not really make anything more secure, so there is little point in trying to nest things like that.

In the case of Sandboxed Application Launcher it is not used much at the time of writing anyhow, but that is not a reason against using it. Flatpak's own sandboxing and Sandboxed Application Launcher can be co-installed without issues, but the latter will be unable to sandbox applications installed through Flatpak. ^[57]

Qubes OS Specific[edit]

At the time of writing, applications installed using Flatpak do not present in the Qubes start menu. ^[58]
Workaround: navigate to Qube settings → applications tab → press "Refresh Applications".

Foreign Sources[edit]

For most use cases the extensive software range available from the official Debian repositories should be sufficient. A selection of nearly 60,000 programs ^[59] can be installed within a couple of steps. These packages are constantly maintained for bug/security fixes and are 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 users will want software that is not yet packaged in Debian. In this case 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. ^[60]

Risks[edit]

Foreign sources should be used infrequently because it can 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]

Foreign sources pose important security implications for the affected 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 ^[archive] to be installed on the system.

In general, the installation of software is a matter of trust. The fact is every installed software source must be trusted. 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. ^[61]

Dependency Hell[edit]

Manually installed packages can contain library versions that are unavailable 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]

To reduce security risks and eliminate the risk of making the workstation unusable, utilize Multiple Whonix-Workstation ™.

Qubes-Whonix ™ users: For installation inside Qubes templates, the risk can only be minimized by using Multiple Qubes-Whonix ™ Templates.

GUI Applications with Root Rights[edit]

Moved to Safely Use Root Commands: Graphical Applications with Root Rights.

Footnotes[edit]

	100px
Fosshost	About Advertisements

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow:

Support:

Donate:

Priority Support | Investors | Professional Support

Whonix ™ | © ENCRYPTED SUPPORT LP | Freedom Software / Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.