{{Header}}
{{title|title=
Installing Newer Tor Versions
}}
{{#seo:
|description=How-to: Install Newer Versions of Tor
|image=Torversioning243231.png
}}
{{tor_mininav}}
[[File:Torversioning243231.png|thumb]]
{{intro|
How-to: Install Newer Versions of Tor
}}
= Introduction =

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Testers only.
}}

Note that a later Tor version will not always be installed from either:

* '''A)''' [[#Install Tor from Backports|Install Tor from Backports]], or
* '''B)''' The Tor Project APT repository -- in the recent past, the Debian <code>bullseye</code> repositories for <code>packages.debian.org</code> and <code>deb.torproject.org</code> had identical Tor versions. In general, as the Debian stable release ages, the likelihood of receiving a newer Tor version from <code>deb.torproject.org</code> increases.

{{Anchor|Newer Tor Versions: {{project_name_short}} Repository}}
{{Anchor|Newer Tor Versions: The Tor Project Repository}}

= The Tor Project APT Repository =

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = If the latest Tor version from ''deb.torproject.org'' has not been fully tested by {{project_name_short}} developers at a specific point in time, then problems can emerge such as broken connectivity. <ref>
At the time of writing Tor v4.2.5 was non-functional in {{project_name_short}}.
</ref> Testers should <u>always</u> maintain a separate, working version of {{project_name_short}} so future connectivity problems can be averted.
}}

If you wish to proceed despite the risk, two steps are required:
* The <code>deb.torproject.org</code> repository must be enabled.
* The [https://github.com/{{project_name_short}}/anon-shared-build-apt-sources-tpo <code>anon-shared-build-apt-sources-tpo</code>] package must be installed, since it enables The Tor Project's APT signing key and installs the apt source ''torproject.sources'' <ref>Alternatively, [https://support.torproject.org/apt/#tor-deb-repo The Tor Project's native instructions for Debian] can be used, but the manual steps are more difficult and involved. The verification of The Tor Project APT signing key is also harder. Since you already [[trust]] {{project_name_short}}, the logical choice is to trust another {{project_name_short}} package to install the right signing key.</ref>
{{Box|text=
{{IconSet|h1|1}} In {{project_name_gateway_long}} (<code>{{project_name_gateway_template}}</code>), [[Operating_System_Software_and_Updates#Updates|update]] the package lists.

{{CodeSelect|code=
sudo apt update
}}

{{IconSet|h1|2}} Install the helper package that adds The Tor Project APT source and signing key.

{{CodeSelect|code=
sudo apt install anon-shared-build-apt-sources-tpo
}}

{{IconSet|h1|3}} ''<u>Optional</u>'': switch to a different Tor Project distribution channel (for example, stable vs experimental).

{{Open with root rights|
filename=/etc/apt/sources.list.d/torproject.sources
}}

Disable the <code>https://deb.torproject.org/torproject.org {{Stable project version based on Debian codename}} main</code> repository by finding the stanza with those settings, and changing <code>Enabled: yes</code> to <code>Enabled: no</code> in it. Then find the stanza for a different [https://deb.torproject.org/torproject.org/dists/ distribution], and enable it by changing that stanza's <code>Enabled: no</code> line to <code>Enabled: yes</code>.

Save the file.

{{IconSet|h1|4}} Update the package lists so the new <code>torproject.sources</code> settings take effect. <ref>So the newly installed <i>/etc/apt/sources.list.d/torproject.sources</i> takes effect.</ref>

{{CodeSelect|code=
sudo apt update
}}

{{IconSet|h1|5}} Install Tor from The Tor Project repository (this may install a newer version).

This step also installs the <code>deb.torproject.org-keyring</code> package which keeps the Tor Project repository apt key up-to-date.

{{CodeSelect|code=
sudo apt install tor deb.torproject.org-keyring
}}
}}

{{Anchor|Onionize Tor Project Updates}}

= Onionize Tor Project APT Repository =

Only follow these instructions if [[#Newer Tor Versions: The Tor Project Repository|Newer Tor versions from The Tor Project Repository]] was configured. Note that The Tor Project deb apt signing key must be added first (see the prior link), or error messages will appear when completing these steps.

{{IconSet|h1|1}} Open <code>torproject.sources</code> in a text editor.

{{Open with root rights|
filename=/etc/apt/sources.list.d/torproject.sources
}}

{{IconSet|h1|2}} Replace the clearnet repository with the onion repository by toggling <code>Enabled:</code>.

Disable the <code>https://deb.torproject.org/torproject.org</code> repository, and enable the <code>tor+http://apow7mjfryruh65chtdydfmqfpj5btws7nbocgtaovhvezgccyjazpqd.onion/torproject.org</code> repository.

{{CodeSelect|code=
#### ENABLED SOURCES ####

Types: deb
URIs: https://deb.torproject.org/torproject.org
Suites: trixie
Components: main
Enabled: no                     # <<<<< change this line from "yes" to "no"
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg

#### DISABLED BY DEFAULT SOURCES ####

Types: deb-src
URIs: https://deb.torproject.org/torproject.org
Suites: trixie
Components: main
Enabled: no
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg

Types: deb deb-src
URIs: https://deb.torproject.org/torproject.org
Suites: tor-experimental-trixie
Components: main
Enabled: no
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg

Types: deb deb-src
URIs: https://deb.torproject.org/torproject.org
Suites: tor-nightly-main-trixie
Components: main
Enabled: no
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg

Types: deb deb-src              # <<<<< Optional: Remove 'deb-src' from this line to save network bandwidth
URIs: tor+http://apow7mjfryruh65chtdydfmqfpj5btws7nbocgtaovhvezgccyjazpqd.onion/torproject.org
Suites: trixie
Components: main
Enabled: yes                    # <<<<< change this line from "no" to "yes"
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg
}}

{{IconSet|h1|3}} Update the package lists so the modified <code>torproject.sources</code> takes effect. <ref>So the modified <i>/etc/apt/sources.list.d/torproject.sources</i> takes effect.</ref>

{{CodeSelect|code=
sudo apt update
}}

{{Anchor|Qubes R4}}

= Install Tor from Backports =
This can be an alternative to Tor installation from The Tor Project's APT Repository, which is documented above.

{{Install Backport|package=
tor
}}

= Install Tor from Source Code =
Advanced users only!

All steps should be performed inside {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>).
{{Box|text=
{{IconSet|h1|1}} Add the Debian <code>sources</code> file so source repositories can be enabled.

{{Open with root rights|filename=
/etc/apt/sources.list.d/debian.sources
}}

{{IconSet|h1|2}} Enable the <code>deb-src</code> repositories required to fetch Tor source and build dependencies.

Find the <code>deb-src</code> stanzas in this file. Enable '''either''' those that contain torified HTTPS addresses '''or''' those that contain onion addresses. To enable a repository, change the line <code>Enabled: no</code> in the repository's stanza to <code>Enabled: yes</code>.

{{IconSet|h1|3}} [[Update]] the package lists after enabling source repositories.

{{CodeSelect|code=
sudo apt update
}}

{{IconSet|h1|4}} Install build dependencies for Tor.

{{CodeSelect|code=
sudo apt build-dep tor
}}

{{IconSet|h1|5}} Fetch the Tor release signing key so the source archive signature can be verified. <ref>
* https://2019.www.torproject.org/docs/signing-keys.html.en
* https://support.torproject.org/tbb/how-to-verify-signature/
* [https://gitlab.torproject.org/tpo/web/support/-/issues/152 stop using gpg keyservers / provide OpenPGP keys for download as files from torproject.org]
* https://gitlab.torproject.org/tpo/web/support/-/issues/139
</ref>

{{Gpg_key_download}}

{{CodeSelect|code=
gpg --keyserver keys.openpgp.org --recv-keys 7A02B3521DC75C542BA015456AFEE6D49E92B601
}}

If the attempt fails, utilize the v3 onion service instead.

{{CodeSelect|code=
gpg --keyserver zkaan2xfbuxia2wpf7ofnkbz6r5zdbbvxbunvp5g2iebopbfc4iqmbad.onion --recv-keys 7A02B3521DC75C542BA015456AFEE6D49E92B601
}}

{{IconSet|h1|6}} Download the Tor source code archive for the desired version.

<u>Note</u>: Replace Tor version <code>{{Tor_upstream_version}}</code> with the actual Tor version to be downloaded.

{{CodeSelect|code=
scurl-download https://dist.torproject.org/tor-{{Tor_upstream_version}}.tar.gz
}}

{{IconSet|h1|7}} Download the OpenPGP signature and verify the source archive.

{{CodeSelect|code=
scurl-download https://dist.torproject.org/tor-{{Tor_upstream_version}}.tar.gz.asc
}}

{{CodeSelect|code=
gpg --verify tor-{{Tor_upstream_version}}.tar.gz.asc
}}

The output should look similar to the following.

<blockquote>gpg: assuming signed data in 'tor-{{Tor_upstream_version}}.tar.gz'
gpg: Signature made Mon 09 Dec 2019 06:21:51 PM UTC
gpg:                using RSA key 7A02B3521DC75C542BA015456AFEE6D49E92B601
gpg: Good signature from "Nick Mathewson <nickm@alum.mit.edu>" [unknown]
gpg:                 aka "Nick Mathewson <nickm@wangafu.net>" [unknown]
gpg:                 aka "Nick Mathewson <nickm@freehaven.net>" [unknown]
gpg:                 aka "Nick Mathewson <nickm@torproject.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 2133 BC60 0AB1 33E1 D826  D173 FE43 009C 4607 B1FB
     Subkey fingerprint: 7A02 B352 1DC7 5C54 2BA0  1545 6AFE E6D4 9E92 B601</blockquote>

{{IconSet|h1|8}} Extract the source archive.

{{CodeSelect|code=
tar xvzf tor-{{Tor_upstream_version}}.tar.gz
}}

{{IconSet|h1|9}} Change into the extracted source directory.

{{CodeSelect|code=
cd tor-{{Tor_upstream_version}}/
}}

{{IconSet|h1|10}} Configure the build and compile Tor from source.

{{CodeSelect|code=
./configure
}}

{{CodeSelect|code=
make
}}

The build should now be finished.

{{IconSet|h1|11}} Verify the version of the newly built Tor binary.

{{CodeSelect|code=
./src/app/tor --version
}}

The output should show.

<blockquote>Tor version {{Tor_upstream_version}}.</blockquote>

{{IconSet|h1|12}} ''{{q_project_name_long}} only'': copy the newly built binary into the {{project_name_gateway_short}} Template (<code>whonix-gw-{{VersionShort}}</code>).

{{CodeSelect|code=
qvm-copy ./src/app/tor
}}

{{IconSet|h1|13}} Stop the currently running Tor service before replacing the binary.

{{CodeSelect|code=
sudo systemctl stop tor
}}

{{IconSet|h1|14}} Replace the system Tor binary with the newly built binary.

{{CodeSelect|code=
sudo cp ./src/app/tor /usr/sbin/tor
}}

Copy the binary again. <ref>
<code>apt-file list tor</code> shows both locations <code>/usr/bin/tor</code> and <code>/usr/sbin/tor</code>.
</ref>

{{CodeSelect|code=
sudo cp ./src/app/tor /usr/bin/tor
}}

{{IconSet|h1|15}} Start Tor again to apply the new binary.

{{CodeSelect|code=
sudo systemctl start tor
}}

The process of installing Tor from source code is now complete.
}}

= Tor Version Downgrade =
It is usually not required to downgrade the Tor version. This should be only used in very specific cases to work around a bug or for testing.

'''1.''' Platform specific notice.

* non-Qubes users: No special notice.
* Qubes users: In Template.

'''2.''' Show available Tor versions.

{{CodeSelect|code=
apt list tor -a
}}

'''3.''' Downgrade for example to Tor version <code>0.4.7.16-1</code>.

Note: The version number was appropriate at time of writing but might need replacement in the future.

{{CodeSelect|code=
sudo apt install tor=0.4.7.16-1 tor-geoipdb=0.4.7.16-1
}}

'''4.''' Platform specific notice.

* non-Qubes users: No special notice.
* Qubes users: Shut down Template.

'''5.''' Reboot.

A reboot of the (VM) running Tor is required.

'''6.''' Done.

The process of Tor version downgrade has been completed.

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

{{Footer}}

[[Category:Documentation]]