{{Title|title=Install Additional Software Safely}}
{{Header}}
{{#seo:
|description=Installing additional Software on {{project_name}}. Safety considerations.
|image=https://www.{{project_clearnet}}/w/images/7/7e/Software-871026-640.jpg
}}
[[image:Software-871026-640.jpg|400px|thumb]]
= Easy =
== Introduction ==
{{mbox
| image   = [[File:Ambox_notice.png|40px]]
| text    =
[[Qubes|{{q_project_name}}]] users need to [https://qubes-os.org/doc/software-update-vm/ install and update persistant software] in the {{workstation_product_name}} Template(s) (<code>{{whonix-ws}}</code>). 
-----
Using APT in the (<code>{{workstation_product_name_vm}}</code>) App Qube will only install software for the current session, with changes being lost when the VM is shut down; see [[#Install_Software_in_an_App_Qube|Install Software in an App Qube]].
}}

A primary {{project name}} 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 {{workstation_product_name}} using [[#APT|APT]], since it is [[Support#Free_Support_Principle|based on Debian]]. However, this is <i>not</i> a recommendation for installing additional software. Also, {{project_name}} is currently the most secure platform for running Tor-unsafe applications like the former Adobe Flash plugin (now deprecated); see the [[Comparison_with_Others#Flash_.2F_Browser_Plugin_Security|operating system comparison]].

The [[Software|{{project_name}} software]] page lists:

* pre-installed {{project name}} 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 <code>package-name</code> with the name of the software to be installed.

{{Install_Package
|package=package-name
}}

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

= Best Practices =

'''Table:''' ''Best Software Installation Practices''

{| class="wikitable"
|-
! scope="col"| '''Domain'''
! scope="col"| '''Advice'''
|-
! scope="row"| Always Verify Signatures
| 
* For greater system security, it is strongly recommended to avoid installing unsigned software. Always make sure that [[Verifying_Software_Signatures|signing keys and signatures are correct]] and/or use mechanisms that heavily simplify and automate this process, like [[Operating_System_Software_and_Updates#Updates|APT upgrades]].
* Note: digital signatures are not a magic bullet. While they increase the certainty that no backdoor was introduced by a third party during transit, this does not mean the software is absolutely "backdoor-free". Learn more about this process and [[Verifying_Software_Signatures#What_Digital_Signatures_Prove|what digital signatures prove]].
|-
! scope="row"| Avoid Manual Software Installation
| 
* Generally avoid the manual installation of packages, even trusted ones. In practice that means software should only be installed with <code>apt</code>, unless special circumstances exist. <ref>
Such as desirable software versions that are not yet bundled in the official repositories.
</ref>
* Other risks: foreign packages are often unsigned, and users may forget to regularly update the software.
|-
! scope="row"| Avoid Third Party Package Managers
| 
* There are many third party package managers besides <code>APT</code>, however many lack the security safeguards that are standard in Debian. Popular examples are <code>pip</code> and <code>node.js</code>.
* The security concern with third party options is they do not verify the code comes from the author. When used, these package managers 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 completely avoid this option. <ref>
https://web.archive.org/web/20170919173146/https://arstechnica.com/information-technology/2017/09/devs-unknowingly-use-malicious-modules-put-into-official-python-repository/
</ref> <ref>
The pip developers refused to implement any kind of proper GPG signature verification, [https://github.com/pypa/pip/issues/1035 opting to support server HTTPS instead] which is a lot weaker. While the TUF secure updater project has [https://theupdateframework.github.io/ implemented a safe version of pip], it is not clear how widely it has been adopted and whether it will become popular.
</ref>
|-
! scope="row"| Prefer APT
| 
* The safest option is to stick with Debian's official package manager <code>APT</code>. This is referenced throughout the wiki whenever the user runs <code>apt</code>.
* <code>APT</code> is a secure package manager which passes the TUF threat model, since it features metadata verification and expiration detection. <ref name=tufaaw>https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md http://www.webcitation.org/6F7Io2ncN
</ref> <ref>
https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html
</ref>
|-
{{Anchor|Prefer Packages from Debian Stable Repository}}
! scope="row"| Prefer Packages from Debian Stable Repository
| 
* Considering the risks, it is safest to install new software from Debian's stable repository, rather than the testing / unstable or third party repositories -- the [https://www.debian.org/doc/manuals/debian-faq/ch-choosing.en.html#s3.1 Debian FAQ] provides a strong rationale for using the stable repository; see footnote. <ref>
<blockquote>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.</blockquote>
</ref>
* Only advanced users should attempt to mix packages from Debian testing or Debian unstable. The reason is it can lead to a [[#Dependency Hell|dependency hell]], making it very difficult to resolve the breakage of APT package management.
* To use newer package versions, see chapter [[#Install Newer Software Versions|Install Newer Software Versions]].
|}

= --no-install-recommends =

Debian's installation default is <code>--install-recommends</code>. Debian packages have various metadata fields such as:
* <code>Depends:</code> dependencies or dependency packages
* <code>Recommends:</code> "recommended" packages
* <code>Suggests:</code> "suggested" packages

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

Debian's default for suggested packages (<code>Suggests:</code>) is <code>--no-install-suggests</code> i.e. not to install suggested packages. Users can optionally use <code>--install-suggests</code>, but there are no known cases where this would be useful at the time of writing. A host of other [https://manpages.debian.org/{{Stable project version based on Debian codename}}/apt/apt.8.en.html#OPTIONS command line options] are also available.

If a package is installed using <code>apt --no-install-recommends install package-name</code>, then re-running <code>apt</code> without any parameters or even with <code>--install-recommends</code> 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 <code>Recommends:</code> can be viewed using <code>apt-cache package-name</code> or by checking the package on https://packages.debian.org.

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

'''Table:''' ''<code>--no-install-recommends</code> Impacts''

{|   class="wikitable"

!| '''Question'''
!| '''Answer'''
|-

| Can using <code>--no-install-recommends</code> lead to security issues?
| No. <ref>There are no known examples at the time of writing.</ref>

|-

| Can using <code>--no-install-recommends</code> lead to missing or broken functionalities?
| Yes. For example, [https://packages.debian.org/search?keywords=mmdebstrap mmdebstrap] uses <code>Recommends:</code> and <code>Suggests:</code> [https://gitlab.mister-muffin.de/josch/mmdebstrap/issues/5 for various optional dependencies providing various functionality].

|-

| Can omitting <code>--no-install-recommends</code> lead to security issues?
| In corner cases, yes. For example consider a [[Host Operating System Selection|host operating system]] without a [[Host Firewall]]. <ref>
Most people nowadays are behind a NAT router which blocks unsolicited incoming connections by default. While that protects from outside Internet-based attacks, it does not protect against attacks launched from inside the local area network (LAN) (devices that use the same router). This is specifically dangerous when using shared WiFi hotspots.
</ref> By omitting <code>--no-install-recommends</code> -- which defaults in using Debian's default <code>--install-recommends</code> -- packages might be installed that open [[Ports|ports]], which can significantly increase attack surface.

|-

| Should <code>--no-install-recommends</code> be used?
| The answer depends on the specific package. Advanced users who know exactly which packages are needed can use <code>--no-install-recommends</code> and afterwards manually add any wanted/additional packages <ref>Perhaps including some recommended packages.</ref> to the <code>apt</code> installation command. Otherwise, there might be corner cases of missing optional dependencies or limited functionality.

|-

| Should {{project name}} set the default to <code>--no-install-recommends</code>? <ref>See: [https://forums.whonix.org/t/set-apt-get-no-install-recommends-by-default/11890 set apt --no-install-recommends by default]</ref>
| This is a good question. It is a big change and could lead to a lot of broken functionality for user-installed packages. At the moment, {{project name}} user [[support]] is manageable because redirection to the [[Free Support Principle]] is possible. If <code>--no-install-recommends</code> was the {{project name}} default, then a lot of functionality might work out of the box in Debian but not in {{project name}}, therefore invalidating the Free Support Principle. 

For these reasons, such suggestions should first be raised at Debian's issue tracker after first searching for existing discussions on Debian mailing lists. Search [https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=apt;dist=unstable Debian APT issue tracker] for <code>recommend</code> first to avoid duplicate issues. For this change to be implemented, it would probably require a lot of research, good examples and a very well written feature request. <ref>This wiki chapter has been authored so it may be a useful resource in the future.</ref>

|-

|}

[[Documentation|{{project name}} documentation]] uses <code>--no-install-recommends</code> whenever appropriate. In general, whether users should use <code>--no-install-recommends</code> for package installation is unspecific to {{project name}} and should be resolved as per [[Free Support Principle]].

= More Security =

== General Advice ==

{{project_name}} users are free to install their favorite software packages, but should be aware that additional software increases the [https://en.wikipedia.org/wiki/Attack_surface attack surface] of the platform. Almost any application can be installed, with a few exceptions for programs that are [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO#Howtotorifyspecificprograms impossible to torify]. In addition, {{project name}} provides:

* protection from IP and DNS leaks (see above for details)
* partial protection against [[Protocol-Leak-Protection and Fingerprinting-Protection|protocol leaks and fingerprinting]], but this is far from perfect

Users are responsible for trying to prevent any other [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO#Protocolleaks protocol leaks] using the [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO "Torify: How-to" guide], but most of those are mitigated by {{project_name}}.

== APT Meta-data ==

When updating with <code>apt</code>, information will leak about which software packages and versions have been installed, unless [[Onionizing_Repositories|Tor onion repositories]] have been configured. <ref>See [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO#Softwareupdaters software updaters] for more information on this topic.</ref> This meta-data cannot be directly linked to any other activity like web browsing, because the {{project name}} <i>apt</i> uwt wrapper forces it to pass through its own circuit. Despite this isolation, it is still possible for updates to be [[Stream Isolation|correlated]] with the same pseudonym. <ref>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 <i>apt</i> 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 [[Ubuntu Tips#About_Ubuntu|custom Ubuntu build]]), or try other attacks against <i>apt</i>.</ref> <ref>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.</ref>

== Recommendations ==

For greater security when updating:

* Follow the guidelines [[#How to install or update with most caution?|below]].
* Be especially careful when adding custom repositories, particularly Personal Package Archives (PPAs).<ref>[https://itsfoss.com/ppa-guide/ Using PPA in Ubuntu Linux (Complete Guide)]: <blockquote>PPA stands for Personal Package Archive. The PPA allows application developers and Linux users to create their own repositories to distribute software. With PPA, you can easily get newer software version or software that are not available via the official Ubuntu repositories.</blockquote></ref> Compared to main distribution repositories, solo developers are more susceptible to influence and theoretically might have malicious intent.
* Read the [[Protocol-Leak-Protection and Fingerprinting-Protection|protocol leak and fingerprinting protection]] entry first. It highlights useful information, like the fact that DNS and IP-related leaks do not apply to {{project_name}}.
* Refer to the Tor Project's [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO Torify: How-to] which discusses various [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TorifyHOWTO#Protocolleaks protocol leaks] and how to mitigate them.
* Review the Tor Project's [https://gitlab.torproject.org/legacy/trac/-/wikis/doc/TransparentProxyLeaks 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. <ref>One option is using [[Tor Controller|Arm]]: <code>Navigate to {{gateway_product_name}} ([[{{q project name short}}|{{q project name}}]]: {{gateway_product_name_vm}})</code> &rarr; <code>Select
Arm - Tor Controller</code> &rarr; <code>Press "n" for a New Identity</code>. <br /> Alternatively: <code>Press "m" for the menu</code> &rarr; <code>Scroll down to "New Identity"</code> &rarr; <code>Press "Enter"</code>.</ref>
# Update using <code>apt</code> 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.

= {{workstation_product_name}} is Firewalled =
{{mbox
| type      = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = '''Note:''' This section is relevant to server software or other advanced / uncommon applications.
}}

The {{gateway_product_name}} firewall <ref>The firewall is found on {{gateway_product_name}}: <i>{{W_Firewall}}</i></ref> has several effects upon {{workstation_product_name}}.

'''Table:''' ''{{gateway_product_name}} Firewall Effects''

{| class="wikitable"
|-

! scope="col"| '''Category'''
! scope="col"| '''Notes'''
|-

! scope="row"| Additional Firewall Restrictions
| The firewall on {{gateway_product_name}} is very restrictive. It can be made even more restrictive by activating options within the firewall script. <ref>
<pre>
         ## Optionally restrict TransPort.
         ## Replace above rule with a more restrictive one, e.g.:
         #$iptables_cmd -t nat -A PREROUTING -i "$int_if_item" -p tcp --match multiport --dports 80,443 --syn -j REDIRECT --to-ports "$TRANS_PORT_WORKSTATION"
</pre>
</ref> It is possible to limit which outgoing ports are redirected to Tor's <code>TransPort</code>. Depending on user intentions, it could also be useful to remove all <code>SocksPort</code>s.
|-

! scope="row"| DNS Requests
| Standard DNS requests on UDP port <code>53</code> are redirected to Tor's <code>DnsPort</code>. <ref>If the DNS server is changed in {{workstation_product_name}} <i>/etc/resolv.conf</i>, this will likely have no effect. The reason is the firewall on {{gateway_product_name}} will redirect all those requests to Tor's <code>DnsPort</code>. The working exception to this rule is when users tunnel / encrypt DNS requests (DNSCrypt, httpsdnsd), as per the [[Secondary DNS Resolver|secondary DNS resolver instructions]].</ref>
|-

! scope="row"| Incoming Connections
| 
* 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|ports]] ("open ports") are blocked.
* Unless explicitly configured, the Ident Protocol / web server listening port is not reachable.
|-

! scope="row"| IPv6
| Tor only [https://gitlab.torproject.org/legacy/trac/-/wikis/org/roadmaps/Tor/IPv6Features partially supports IPv6], although full implementation is likely in the near term. <ref>
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: [https://gitlab.torproject.org/legacy/trac/-/wikis/org/roadmaps/Tor/IPv6 IPv6 roadmap].
</ref> This is not a {{project_name}}-specific issue. <ref>
https://phabricator.whonix.org/T509
</ref>
|-

! scope="row"| Server Services
| [[Onion Services]] and/or [[Hosting_Location_Hidden_Services|Location Hidden Services]] can be hosted.
|-

! scope="row"| Tor Routing
| {{TorifiedGateway}} Refer to the footnotes for further information.
|-

! scope="row"| UDP
| [[Tor#UDP|Tor does not support UDP]]. This is not a {{project_name}}-specific issue.
|-

|}

Related topics:

* [[{{gateway product name short}}_Firewall|{{gateway_product_name}} Firewall]]
* [[{{workstation product name short}}_Firewall|{{workstation_product_name}} Firewall]]
* [[Ports]]

= Advanced =
== Install Newer Software Versions ==
{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = <u>Prerequisite knowledge</u>: refer to the [[Operating_System_Software_and_Updates#Frozen_Packages|Frozen Packages]] entry in the [[Operating_System_Software_and_Updates|Operating System Software and Updates]] chapter.
}}

It is sometimes possible to install newer versions of software applications, either via available  [[#Backports|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 [https://gitlab.com/whonix/binaries-freedom <code>binaries-freedom</code> Debian package] in {{project name}} ships Electrum. It comes with the appimage file (<code>/usr/share/binaries-freedom/electrum-appimage/electrum-4.0.7-x86_64.AppImage</code>) and a start menu entry (<code>/usr/share/applications/electrum-appimage.desktop</code>). 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 <code>binaries-freedom</code> package is intended to improve usability and it was never designed to limit customization, nor does it have that side effect. As per {{project name}} policy there are [[Reasons for Freedom Software#no_intentional_user_freedom_restrictions|No Intentional User Freedom Restrictions]]. <ref>In simple terms, {{project name short}} modifications can be ignored.</ref>

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

# [[Electrum#Uninstallation|uninstalling <code>binaries-freedom</code> (electrum appimage)]]
# 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 {{project name}} and therefore the [[Free Support Principle]] applies to installation steps. The same is true for {{Q project name}} users -- first consider how this process would be achieved in a Debian-based Qubes template.

== Enable Debian Backports Repository ==
<u>Operating System Specific Notes</u>:

* [[File:logo_box.png|25px|link=]] {{project name}} VM users: Should skip this step! Debian APT backports repository is already default in {{project name}} version <code>16</code> and above.
* [[File:Debian.png|15px|link=]] Debian: The following instructions are for Debian host operating system or Debian VM users.

'''1.''' Boot the virtual machine. (Qubes: <code>debian-{{Stable project version based on Debian version short}}</code> Template).

'''2.''' Add the current Debian stable backports codename <code>{{Stable_project_version_based_on_Debian_codename}}-backports</code> to Debian apt sources.

<u>Notes</u>:

* This applies to Debian <code>{{VersionShort}}</code>. Later Debian versions will use a codename different to <code>{{Stable_project_version_based_on_Debian_codename}}</code>.
* Advanced users note: Instructions for torification of the fasttrack clearnet repository or fasttrack onion repository can be found in the following footnote.

Run. <ref>
Alternatively, users who like torify over clearnet can add <code>tor+</code>. 

{{CodeSelect|code=
sudo su -c "echo -e 'deb tor+https://deb.debian.org/debian {{Stable_project_version_based_on_Debian_codename}}-backports main contrib non-free' > /etc/apt/sources.list.d/backports.list"
}}

Alternatively, users who like [[Onionizing Repositories]] can use the onion instead.

{{CodeSelect|code=
sudo su -c "echo -e 'deb tor+http://{{Debian_onion}}/debian {{Stable_project_version_based_on_Debian_codename}}-backports main contrib non-free' > /etc/apt/sources.list.d/backports.list"
}}
</ref>

{{CodeSelect|code=
sudo su -c "echo -e 'deb https://deb.debian.org/debian {{Stable_project_version_based_on_Debian_codename}}-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 <code>{{Stable_project_version_based_on_Debian_codename}}</code> to <code>{{Debian_Codename_Testing}}</code>. <ref>
Most often this step applies before attempting major {{project name}} upgrades; upgrade instructions are also made available at that time (see [[Stay_Tuned|Stay Tuned]]).
</ref> To proceed, run.

{{CodeSelect|code=
sudo rm /etc/apt/sources.list.d/backports.list
}}

== Enable Debian Fasttrack Repository ==
<u>Operating System Specific Notes</u>:

* [[File:logo_box.png|25px|link=]] {{project name}} VM users: Should skip this step! Debian APT fasttrack repository is already default in {{project name}} version <code>16</code> and above.
* [[File:Debian.png|15px|link=]] Debian: The following instructions are for Debian host operating system or Debian VM users.

'''1.''' Boot the Debian VM. (Qubes: <code>debian-{{Stable project version based on Debian version short}}</code>) Template.

'''2.''' Install the <code>fasttrack-archive-keyring</code> package.

{{Install Package||package=
fasttrack-archive-keyring
}}

'''3.''' Add the current Debian fasttrack APT repository.

<u>Notes</u>:

* This applies to Debian <code>{{VersionShort}}</code>. Later Debian versions will use a codename different to <code>{{Stable_project_version_based_on_Debian_codename}}</code>.
* Advanced users note: Instructions for torification of the fasttrack clearnet repository or fasttrack onion repository can be found in the following footnote.

Run. <ref>
Alternatively, users who like torify the clearnet repository can add <code>tor+</code>.

{{CodeSelect|code=
sudo su -c "echo -e 'deb tor+https://fasttrack.debian.net/debian/ {{Stable_project_version_based_on_Debian_codename}}-fasttrack main contrib non-free' > /etc/apt/sources.list.d/fasttrack.list"
}}

[https://salsa.debian.org/fasttrack-team/support/-/issues/27 It is not yet possible to set an <i>.onion</i> mirror for fastrack.]
</ref>

{{CodeSelect|code=
sudo su -c "echo -e 'deb https://fasttrack.debian.net/debian/ {{Stable_project_version_based_on_Debian_codename}}-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 <code>{{Stable_project_version_based_on_Debian_codename}}</code> to <code>{{Debian_Codename_Testing}}</code>. <ref>
Most often this step applies before attempting major {{project name}} upgrades; upgrade instructions are also made available at that time (see [[Stay_Tuned|Stay Tuned]]).
</ref> To proceed, run.

{{CodeSelect|code=
sudo rm /etc/apt/sources.list.d/fasttrack.list
}}

== Backports ==
[http://backports.debian.org Debian Backports]:

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

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

<blockquote>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!</blockquote>

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Replace <code>package-name</code> below with the package you actually want to install.
}}

{{Install Backport|package=
package-name
}}

== Fasttrack ==
[http://fasttrack.debian.net Debian Fasttrack]:

<blockquote>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.</blockquote>

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

<blockquote>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!</blockquote>

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Replace <code>package-name</code> below with the package you actually want to install.
}}

{{Install Fasttrack|package=
package-name
}}

== Install from Debian Testing ==

=== Warnings ===

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Mixing packages from Debian <code>stable</code> with those from a later release like <code>testing</code> can destabilize the system due to associated software [[#Dependency_Hell|dependencies]] required for full functionality.
}}

Before completing steps in this section, first read [[#Prefer Packages from Debian Stable Repository|Prefer Packages from Debian Stable Repository]]. Carefully check how packages will change before proceeding -- a host of upgrades is usually safe, but no {{project name}} packages should be removed as part of the process; see [[{{project name short}} Debian Packages]]. Be aware that problems are still possible; see [https://forums.whonix.org/t/modulenotfounderror-no-module-named-distutils-spawn/6826 here] for an example. 

It is recommended to complete this process in a [[Multiple Whonix-Workstation|separate {{workstation_product_name}}]] (<code>{{whonix-ws}}-debian-testing-mix</code>) due to the risks. Ask for advice in the forums on a case-by-case basis.

=== Procedure ===

{{Box|text=
'''1.''' Boot the {{workstation_product_name}} (<code>{{whonix-ws}}-debian-testing-mix</code>) Template.

'''2.''' Add the current Debian testing codename <code>{{Debian_Codename_Testing}}</code> to ''sources.list'' 

Note: this applies to {{project name}} 16. Later {{project name}} versions may use a codename different to <code>{{Debian_Codename_Testing}}</code>.

In the {{workstation_product_name}} (<code>{{whonix-ws}}-debian-testing-mix</code>) Template, run.

{{CodeSelect|code=
sudo su -c "echo -e 'deb http://http.debian.net/debian {{Debian_Codename_Testing}} main' > /etc/apt/sources.list.d/testing.list"
}}

Or alternatively use the <i>.onion</i> mirror. 

{{CodeSelect|code=
sudo su -c "echo -e 'deb tor+http://{{Debian_onion}}/debian {{Debian_Codename_Testing}} main' > /etc/apt/sources.list.d/testing.list"
}}

'''3.''' [[Update#Updates|Update]] the package lists.

{{CodeSelect|code=
sudo apt update
}}

'''4.''' Install the select software.

{{CodeSelect|code=
sudo apt -t {{Debian_Codename_Testing}} install packagename
}}

* Replace <code>packagename</code> 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 <code>{{Stable_project_version_based_on_Debian_codename}}</code> to <code>{{Debian_Codename_Testing}}</code>. <ref>Most often this step applies before attempting major {{project name}} upgrades; upgrade instructions are also made available at that time (see [[Stay_Tuned|Follow {{project_name}} Developments]]).</ref> To proceed, run.

{{CodeSelect|code=
sudo rm /etc/apt/sources.list.d/testing.list
}}
}}

== Install from Debian Unstable ==

=== Warnings ===

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = Managing security updates for the "stable" distribution remains the highest priority for the Debian security team. This means security fixes for Debian "unstable" are managed by the contributors themselves and not by the Debian security team. Therefore, "unstable" does not receive security updates in a timely manner. <ref>https://www.debian.org/releases/sid/</ref> <ref>https://www.debian.org/security/faq#unstable</ref> 
}}

Before completing steps in this section, first read [[#Prefer Packages from Debian Stable Repository|Prefer Packages from Debian Stable Repository]].

Mixing packages from Debian <code>stable</code> with those from a later release like <code>unstable</code> can destabilize the system due to associated software [[#Dependency_Hell|dependencies]] required for full functionality. First carefully check how packages will change before proceeding. <ref>See: https://wiki.debian.org/DebianUnstable#What_are_some_best_practices_for_testing.2Fsid_users.3F</ref> 

A host of upgrades is usually safe, but no {{project name}} packages should be removed as part of the process; see [[{{project name short}} Debian Packages]]. It is recommended to complete this process in a [[Multiple Whonix-Workstation|separate {{workstation_product_name}}]] (<code>{{whonix-ws}}-debian-unstable-mix</code>) due to the risk. Ask for advice in the forums on a case-by-case basis.

=== Procedure ===

{{Install Unstable|
package=package-name
}}

== Package Reinstallation ==

As per the [[Support#Free_Support_Principle|free support principle]], package reinstallation utilizes normal Debian processes.

The example below shows how the <code>thunderbird</code> package would be reinstalled. It is possible to  substitute <code>thunderbird</code> 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 <code>tor</code>, because the reinstallation would be very difficult and is currently [[unsupported]].

Even in the <code>thunderbird</code> package example, dependency complications emerge. In the example below the <code>qubes-whonix-workstation-packages-recommended</code> package also depends on <code>thunderbird</code>. Further, the <code>qubes-whonix-workstation</code> package depends on <code>qubes-whonix-workstation-packages-recommended</code>.

{{Box|text=
'''1.''' Update the package lists and upgrade. 

See [[Operating_System_Software_and_Updates#Updates|Updates]] for instructions.

'''2.''' Purge the package you want to reinstall.

{{CodeSelect|code=
sudo apt purge thunderbird
}}

The output will show something like the following.

<pre>
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) ...
</pre>

The packages <code>qubes-whonix-workstation-packages-recommended</code> and <code>qubes-whonix-workstation</code> have been inadvertently uninstalled due to technical limitations. <ref>[[{{project name short}}_Debian_Packages#Technical_Stuff]]</ref> These packages are reinstalled at a later step.

'''3.''' Delete the user configuration folder if that is desired. 

In this <code>thunderbird</code> example, the user configuration folder is specified below (it changes depending on the package).

{{CodeSelect|code=
rm -r ~/.thunderbird
}}

'''4.''' Reinstall the <code>thunderbird</code> package and the additional packages that were purged. 

The <code>--no-install-recommends</code> parameter below is optional.

{{CodeSelect|code=
sudo apt install --no-install-recommends thunderbird qubes-whonix-workstation-packages-recommended qubes-whonix-workstation
}}

Related to: [[{{project name short}} Debian Packages]].
}}

== Install Software in an App Qube ==

{{mbox
| type      = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = [[Qubes|{{q_project_name}}]] only! Custom scripting is recommended, which is beyond the scope of this entry. Use a search engine to locate free articles and instructions on this process.   
}}

There is no reason to avoid installing software in [https://www.qubes-os.org/doc/glossary/#app-qube App Qubes], 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 ===

This software installation method means a single [https://www.qubes-os.org/doc/glossary/#vm VM] assumes many of the positive characteristics found in both App Qubes and [https://www.qubes-os.org/doc/glossary/#standalone Standalones].

*<u>Centralized Updates:</u> [https://www.qubes-os.org/doc/glossary/#app-qube App Qubes] are based on a [https://www.qubes-os.org/doc/glossary/#template Template]. 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. <ref name="qubes-software">[https://www.qubes-os.org/doc/how-to-install-software/ How to install software]</ref>
*<u>Minimal Disk Usage:</u> 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 <code>/home</code> directory.
*<u>Semi-persistent Storage:</u> User data stored in <code>/home</code> , <code>/rw</code> and <code>/usr/local</code> survives reboot. Many applications like [https://www.whonix.org/wiki/Signal Signal] and [https://en.wikipedia.org/wiki/Wire_(software) Wire] store user data in the <code>/home</code> folder. Since the custom script installs the software seamlessly with little or no user interaction, the App Qube has <i>"quasi-full persistence"</i>, not unlike a Standalone's full persistence.

=== App Qube Preparation ===
{{Box|text=
'''1.''' Create an App Qube based on <code>{{whonix-ws}}</code>.

'''2.''' Pre-install any necessary dependencies.

Dependencies are available from [https://packages.debian.org/stable/ packages.debian.org] and can be pre-installed in the Template to speed up the repetitive software installation process. This means only packages or software missing from [https://packages.debian.org/stable packages.debian.org] will be repeatedly installed in the App Qube.

'''3.''' Create a custom script that runs at VM boot. 

The purpose of this script is to automate software installation that would otherwise require manual user steps. Note that script functionality is variable, dependent on the software packages being installed and the experience of the user.

Scripting is useful for common tasks like:  

* adding specific software repositories
* importing verified signing keys
* updating the package list with <code>apt update</code>, after the repository and signing key are imported
* finally running <code>apt install</code> to install the relevant software package(s)
}}

=== App Qube Use ===

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = The App Qube's root filesystem does not provide a strong [https://www.qubes-os.org/doc/templates/#note-on-treating-app-qubes-root-filesystem-non-persistence-as-a-security-feature non-persistent security feature]. The persistence of the <code>/home</code>, <code>/rw</code>, and <code>/usr/local</code> filesystem means malware can be specifically written to target Qubes-based App Qubes, inserting hooks inside these directory's files. <ref>https://www.qubes-os.org/doc/templates/#note-on-treating-app-qubes-root-filesystem-non-persistence-as-a-security-feature</ref> <ref>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.</ref>
}}

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 <code>/home</code> 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 [https://www.qubes-os.org/doc/bind-dirs/ 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 ==
{{Launcher
|name=program-name
|path=/path/to/program
|categories=Other
}}

== snap ==

General forum discussion about snap: [https://forums.whonix.org/t/snap-store-snaps-snapd-snapcraft-io-a-new-software-source/7631 Snap Store / snaps / snapd / snapcraft.io - a new software source?]

[[{{q project name short}}|{{q project name}}]] issues:

* Efforts to persistently install snap apps in [[{{q project name short}}|{{q project name}}]] via [https://www.qubes-os.org/doc/bind-dirs/ bind-dirs] or with snap proxy settings have been unsuccessful. This means it must be [[#Install_Software_in_an_App_Qube|installed in an App Qube]] on every occasion it is required. Efforts to improve this situation are most welcome, see: [https://forums.whonix.org/t/wickr-me-vs-qubes-whonix-persistence/9593 Wickr Me vs Qubes-Whonix Persistence] and [https://forums.whonix.org/t/snap-totally-unusable-on-whonix-ws/10146 snap totally unusable on Qubes whonix-ws].
* Qubes Templates are non-networked by default, <ref>APT works because of Qubes' qrexec-based updates proxy.</ref> which means snap does not run inside <code>{{whonix-ws}}</code> 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 {{project name}}.

== Flatpak ==

=== Introduction ===

[https://flatpak.org Flatpak] is: <ref>https://en.wikipedia.org/wiki/Flatpak</ref>
<blockquote>...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.</blockquote>

There are several advantages of utilizing Flatpak: <ref>https://en.wikipedia.org/wiki/Flatpak#Features</ref> <ref>https://en.wikipedia.org/wiki/Flatpak#Support</ref> <ref>https://docs.flatpak.org/en/latest/introduction.html</ref>
* Packages are easily added via Flathub, which is a repository located at <code>flathub.org</code>; for a {{project_name}} example, see [[Dev/OnionShare|here]].
* Numerous Linux distributions are either supported out-of-the-box or after the <code>flatpak</code> package is installed; Debian is a supported platform (which {{project_name}} is based upon).
* Desktop applications are sandboxed and have limited access to the host environment. <ref>Although Firejail cannot be run in conjunction with Flatpak.</ref>
* Flatpak bundles are a single-file format which contains the application or runtime. <ref>Runtimes are basic dependencies that are used by packages.</ref>
* 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 [https://flatpak.org/faq/ Flatpak FAQ] and [https://docs.flatpak.org/en/latest/index.html Flatpak documentation].

=== Flatpak Package Manager Security ===

This entry compares Flatpak security features (such as signed metadata) against Debian's APT package manager. <ref>Note that source code is not considered in this comparison.</ref> With one caveat, Flatpak package manager security is comparable to Debian's APT package manager: [https://github.com/flatpak/flatpak/issues/4031#issuecomment-748891490 Flatpak currently does not defend against <code>indefinite freeze attacks</code>].

A definition of <code>indefinite freeze attacks</code> is provided by {{TUF4}}:

<blockquote>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.</blockquote>

For many adversaries this attack is difficult because it requires breaking [[SSL|TLS]]. While Flatpak package version information is not protected by a [https://github.com/flatpak/flatpak/issues/4031#issuecomment-753581447 <code>valid-until</code> field], 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: 
* <code>Break Tor</code> &rarr; <code>Target specific user(s)</code> &rarr; <code>Break TLS</code> &rarr; <code>Mount an indefinite freeze attack</code> &rarr; <code>Exploit a vulnerability caused by an outdated software version</code>.

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 <code>Additional information</code> section that lists <code>Updated</code> and <code>Version</code> information. For example, at the time of writing for [[Chromium]]:
* This is the associated [https://flathub.org/apps/details/org.chromium.Chromium org.chromium.Chromium flathub website page]. 
* The additional information section lists:
** <code>Updated</code>: <code>October 5, 2021</code>
** <code>Version</code>: <code>94.0.4606.71</code>

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. <ref>In theory some adversaries are capable of mounting an indefinite freeze attack against all visitors arriving from the Tor network. This is considered unlikely because the threat of eventual detection is too high. Such an attack would be widely publicized and might lead to major improvements in how Internet encrypted/authenticated connections are established.
</ref>

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). <ref>[[Dev/Chromium#Remotely_Exploitable_Chromium_Security_Vulnerability_CVE-2021-21193_exploited_in_the_wild|Chromium exploitation example]].</ref> 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 [[#Install_from_Debian_stable|stable]] (with [[Operating_System_Software_and_Updates#Frozen_Packages|Frozen Packages]]) (or [[#Install Newer Software Versions|newer]]).

Forum discussion: 
* [https://forums.whonix.org/t/flatpak-as-a-software-source-flathub-as-a-source-of-software/8500 flathub as a source of software].

=== Flatpak Sandbox Security ===

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 [[Mental_Model#Threat_Modeling|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. <ref>
https://github.com/flatpak/flatpak/issues/4032
</ref>

Flatpak's own sandboxing capabilities interfere with other sandboxing initiatives like [[sandbox-app-launcher|Sandboxed Application Launcher]] and [[Whonix-Workstation_Security#Firejail|Firejail]]: <ref>https://flatpak.org/faq/</ref>
<blockquote>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.</blockquote> 

In the case of [[sandbox-app-launcher|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 [[sandbox-app-launcher|Sandboxed Application Launcher]] can be co-installed without issues, but the latter will be unable to sandbox applications installed through Flatpak. <ref>
[https://forums.whonix.org/t/flatpak-as-a-software-source-flathub-as-a-source-of-software/8500/19 FlatPak as a Software Source / flathub as a source of software].
</ref>

=== Qubes OS Specific ===

At the time of writing, applications installed using Flatpak do not present in the Qubes start menu. <ref>
[https://github.com/QubesOS/qubes-issues/issues/6325 flatpak installed applications do not show up in Qubes start menu]
</ref> <br />Workaround: <code>navigate to Qube settings</code> &rarr; <code>applications tab</code> &rarr; <code>press "Refresh Applications"</code>.

= Foreign Sources =

For most use cases the extensive software range available from the official Debian repositories should be sufficient. A selection of nearly 60,000 programs <ref>https://www.debian.org/intro/why_debian</ref> 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 <i>.deb</i> binary, or directly compiled source packages. <ref>https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html</ref>

== Risks ==
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 ===
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 [https://en.wikipedia.org/wiki/Trojan_horse_%28computing%29 Trojan horses] 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. <ref>With reproducible package builds on the horizon, the security risk from the second factor will be minimal in the future.</ref>

=== Dependency Hell ===
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 ===

To reduce [[#Security Issues|security risks]] and eliminate [[#Dependency Hell|the risk of making the workstation unusable]], utilize [[Multiple Whonix-Workstation|Multiple {{workstation_product_name}}]].

{{Q project name}} users: For installation inside Qubes templates, the risk can only be minimized by using [[Multiple Qubes-Whonix TemplateVMs|Multiple {{Q project name}} Templates]].

= GUI Applications with Root Rights =
Moved to [[root#Graphical Applications with Root Rights|Safely Use Root Commands: Graphical Applications with Root Rights]].

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]
