Skip to content

GitLab

Last edited by Matthew Finkel
Page history

Updating

Tor Browser provides a built-in automatic updating process. This is currently the only supported way of maintaining an updated browser.

The update URL is: https://aus1.torproject.org/torbrowser/update_3/

The current versions can be seen using this URL (stable and alpha, respectively):

On Unix-like systems, piping this through jq is suggested:

curl https://aus1.torproject.org/torbrowser/update_3/release/downloads.json | jq -r . | less

Current updates (on Linux 64-bit, en-US locale) use a URL like:

When updating from a version of Tor Browser older than 8.0, due to the watershed the URL is something like:

Update Watersheds

Over the years since Tor Browser began using automatic updates, the requirements of updating changed a few times. These changes were implemented by migrating to a new update location. These were watershed updates.

Ticket Path Release
#19316 (closed) update_3 6.5.2
#26050 (closed) update_3 8.0a10

History

MAR files were signed beginning in 2014, with ticket #13379 (closed). Incremental mar files were implemented in #13324 (closed),

Manually Applying MAR Update

These instructions are based on https://wiki.mozilla.org/Software_Update:Manually_Installing_a_MAR_file

Linux:

  1. We assume the Tor Browser installation directory is /path/to/torbrowser, this is the directory normally named tor-browser_${LOCALE} (like tor-browser_es-ES/ and it contains the Browser/ directory)
  2. Create a directory somewhere your user can read/write/execute, such as in your home directory (let's call it app-update).
  3. Download incremental MAR file, such as tor-browser-linux64-9.5a6-9.5a7_es-ES.incremental.mar (most likely from https://dist.torproject.org/torbrowser/)
  4. Move .mar file into the app-update directory
  5. Rename .mar file as update.mar
  6. Copy updater and updater.ini into the same directory as above (cp /path/to/torbrowser/Browser/updater* /path/to/app-update/)
  7. Change directory into the app-update directory (cd /path/to/app-update/)
  8. Run updater (LD_LIBRARY_PATH=/path/to/torbrowser/Browser ./updater /path/to/app-update /path/to/torbrowser/Browser /path/to/torbrowser/Browser)
  9. This requires setting LD_LIBRARY_PATH with the directory containing Tor Browser's Firefox libraries
  10. Replace /path/to/torbrowser with the correct path on your computer
  11. ALL PATHS MUST BE ABSOLUTE, FULL PATHS beginning with "/"
  12. After this command is executed, an update.status file should be created in app-update/. If the update was applied successfully, then the file should contain "succeeded".
  13. After successfully applying the update, simply delete the app-update/ directory

MacOS:

  1. Create a directory somewhere your use can read/write/execute, such as in your home directory (let's call it app-update).
  2. Open Applications and open the context menu of Tor Browser.app, select "Show Package Contents`
  3. After showing the package content, open Contents/MacOS/ and copy Tor Browser Software Update (updater.app) into app-update (created above)
  4. Download incremental MAR file, such as tor-browser-osx64-9.5a6-9.5a7_es-ES.incremental.mar (most likely from https://dist.torproject.org/torbrowser/)
  5. Move the downloaded .mar file into the app-update directory
  6. Rename .mar file as update.mar
  7. Open a Terminal and change directory into the Tor Browser installation (cd /Applications/Tor\ Browser.app/)
  8. Run the updater program (we assume the app-update directory is in your Home, and set DYLD_LIBRARY_PATH as directory where the libraries are located
  9. $ DYLD_LIBRARY_PATH=Contents/MacOS/ ~/app-update/updater.app/Contents/MacOS/org.mozilla.updater ~/app-update /Applications/Tor\ Browser.app/ /Applications/Tor\ Browser.app/ (the installation directory is provided twice in this command)
  10. After this command is executed, an update.status file should be created in ~/app-update/. If the update was applied successfully, then the file should contain "succeeded".
  11. After successfully applying the update, simply delete the app-update/ directory

Windows:

NOTE: These steps assume you installed Tor Browser in the default installation location: %USERPROFILE%\Desktop\Tor Browser. If you have installed Tor Browser somewhere else, you will need to update the commands referencing the Tor Browser installation directory to point to your custom installation path. Also note that %USERPROFILE% expands to the current user's home directory. For most users this is C:\Users\%USERNAME%.

  1. Ensure that Tor Browser is not running.
  2. Open an un-elevated command prompt by Win+R, typing cmd.exe in the resulting prompt, and hitting the OK button.
  3. From the command prompt, create a temporary directory by:
  • mkdir %USERPROFILE%\app-update
  1. Download incremental MAR file, such as tor-browser-win64-9.5a6-9.5a7_en-US.incremental.mar (most likely from https://dist.torproject.org/torbrowser/) and save it in your app-update directory.
  2. Rename your downloaded MAR file to update.mar
  3. Copy the updater.exe shipped with Tor Browser to your app-update directory:
  • copy "%USERPROFILE%\Desktop\Tor Browser\Browser\updater.exe" %USERPROFILE%\app-update
  1. Change your working directory to your Tor Browser installation path:
  • cd "%USERPROFILE%\Desktop\Tor Browser\Browser"
  1. Run the updater:
  • %USERPROFILE%\app-update\updater.exe %USERPROFILE%\app-update "%USERPROFILE%\Desktop\Tor Browser\Browser" "%USERPROFILE%\Desktop\Tor Browser\Browser"
  1. After this command is executed, an update.status file should be created in %USERPROFILE%\app-update. If the update was applied successfully, then the file should contain "succeeded". You can verify this by:
  • type %USERPROFILE%\app-update\update.status In the event of error, you can examine %USERPROFILE%\update.log to troubleshoot the problem.
  1. Cleanup the app-update directory
  • rmdir /S /Q %USERPROFILE%\app-update

MAR Troubleshooting

The provided updater program is not very user friendly and will not provide immediate user feedback in the event of failure. If the update.status file says anything besides "succeeded" you can examine the generated updater.log in your created app-update directory for clues. The most likely cause of error is using a MAR file that is not compatible with your Tor Browser installation. Unfortunately there are multiple ways in which you can use the wrong MAR file:

CPU an OS Architecture

First, you must be sure that the OS and and CPU architecture match between the MAR file and your Tor Browser installation:

MAR Architecture
linux32 32-bit x86 Linux
linux64 64-bit amd64 Linux
osx64 64-bit macOS
win32 32-bit Windows
win64 64-bit Windows

You can determine 'bitness' of your Tor Browser installation by launching Tor Browser and navigating through Hamburger Menu -> Help -> About Tor Browser. There should be a line in the resulting pop-up similar to 9.5a7 (based on Mozilla Firefox 68.5.0esr) (64-bit). Please note that it is typically possible to run 32-bit software on a 64-bit OS, so please be sure to check you have this right if your update fails.

Just because you are running 64-bit Windows or Linux does not mean you need the 64-bit MAR file!

The updater.log file will likely complain about mismatched file names if you use a MAR file for the wrong OS. It will likely complain about mismatched file sizes if you use a MAR file with the wrong CPU architecture.

Correct Incremental Version

Second, if you are updating using an incremental MAR file (these MAR files end in .incremental.MAR) be sure that the 'from' version matches your Tor Browser installation's version. The incremental mar file's have a filename in the form: tor-browser-$ARCH-$FROM_VERSION-$TO_VERSION_$LOCALE.incrementalmar. For example, an incremental update from the American English 32-bit Windows Tor Browser version 9.5a6 to version 9.5a7 has the filename: tor-browser-win32-9.5a6-9.5a7_en-US.incremental.mar

You can determine the version number by launching Tor Browser and looking at the top-right hand corner of about:tor (for left-to-right languages). The version can also be found in the About Tor dialog as described in the previous section.

The updater.log file will likely complain about mismatched file sizes if you use the wrong incremental version.

Testing Updater

Testing the updater (and update process) is non-trivial. There are three separate modifications that must be made within the Tor Browser build environment.

  1. Update URL
  2. Signature public key
  3. Nightly build configuration file

In addition, you must create a new public key pair for signing mar files. Copy the resulting public certificate marsigner.der for later use, too.

Updater URL

Testing the nightly channel is easiest. The URL can be modified in the build script. If you are testing release or alpha then a more complicated patch will be needed.

Signature Public Certificate

After creating the new testing key pair, add the new certificate into tor-browser by overwriting the appropriate secondary key. For nightly, you can achieve this with a patch

diff --git a/projects/firefox/build b/projects/firefox/build
index 732da0f36d52..354145dece4d 100644
--- a/projects/firefox/build
+++ b/projects/firefox/build
@@ -102,7 +102,10 @@ tar -C browser/extensions -xf $rootdir/[% c('input_files_by_name/tor-launcher')
 
 [% IF c("var/nightly") -%]
   # Set update url for nightly (#33402 / #40033)
-  sed -i 's|^URL=https://aus1\.torproject\.org/.*|URL=https://nightlies.tbb.torproject.org/nightly-updates/updates/nightly-[% c("var/osname") %]/%CHANNEL%/%BUILD_TARGET%/%VERSION%/%LOCALE%|' build/application.ini.in
+  #sed -i 's|^URL=https://aus1\.torproject\.org/.*|URL=https://nightlies.tbb.torproject.org/nightly-updates/updates/nightly-[% c("var/osname") %]/%CHANNEL%/%BUILD_TARGET%/%VERSION%/%LOCALE%|' build/application.ini.in
+  sed -i 's|^URL=https://aus1\.torproject\.org/.*|URL=https://people.torproject.org/~sysrqb/update_3/%CHANNEL%/%BUILD_TARGET%/%VERSION%/%LOCALE%|' build/application.ini.in
+
+  cp $rootdir/marsigner.der toolkit/mozapps/update/updater/nightly_aurora_level3_secondary.der
 [% END -%]
 
 rm -f configure
diff --git a/projects/firefox/config b/projects/firefox/config
index 006c3c9d7c68..fa59b712776e 100644
--- a/projects/firefox/config
+++ b/projects/firefox/config
@@ -168,3 +170,4 @@ input_files:
     # TorButton patch authored by Arthur Edelstein, from https://github.com/arthuredelstein/torbutton/ branch 2.1.10-namecoin
   - filename: namecoin-etld.patch
     enable: '[% c("var/namecoin") %]'
+  - filename: marsigner.der

Import Public Certificate

nssdb="/path/to/nssdb"
mkdir $nssdb
mar_tools="path/to/mar-tools"
pubkey="/path/to/marsigner.der"
$mar_tools/certutil -A -n marsigner -d $nssdb -t ,, -i $pubkey

Sign MAR file

mar_tools="path/to/mar-tools"
nssdb="/path/to/nssdb_public"
marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
mkdir signed

$mar_tools/signmar -d $nssdb -n marsigner -s $marfile signed/$marfile

Verify Signed MAR file

  1. Using the same database containing the private key material
mar_tools="path/to/mar-tools"
nssdb="/path/to/nssdb"
marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
mkdir signed

$mar_tools/signmar -d $nssdb -n marsigner -v signed/$marfile
  1. Using a separate database with only the public certificate
mar_tools="path/to/mar-tools"
nssdb="/path/to/nssdb_public"
marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
mkdir signed

$mar_tools/signmar -d $nssdb -n marsigner -v signed/$marfile