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 || update_3 || 6.5.2 ||
|| #26050 || update_3 || 8.0a10 ||
== History ==
MAR files were signed beginning in 2014, with ticket #13379. Incremental mar files were implemented in #13324,
== 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)
1. Create a directory somewhere your user can read/write/execute, such as in your home directory (let's call it `app-update`).
1. 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/)
1. Move .mar file into the `app-update` directory
1. Rename .mar file as `update.mar`
1. Copy `updater` and `updater.ini` into the same directory as above (`cp /path/to/torbrowser/Browser/updater* /path/to/app-update/`)
1. Change directory into the `app-update` directory (`cd /path/to/app-update/`)
1. Run updater (`LD_LIBRARY_PATH=/path/to/torbrowser/Browser ./updater /path/to/app-update /path/to/torbrowser/Browser /path/to/torbrowser/Browser`)
1. This requires setting LD_LIBRARY_PATH with the directory containing Tor Browser's Firefox libraries
1. Replace `/path/to/torbrowser` with the correct path on your computer
1. ALL PATHS MUST BE ABSOLUTE, FULL PATHS beginning with "/"
1. 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".
1. 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`).
1. Open `Applications` and open the context menu of `Tor Browser.app`, select "Show Package Contents`
1. After showing the package content, open `Contents/MacOS/` and copy `Tor Browser Software Update` (`updater.app`) into `app-update` (created above)
1. 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/)
1. Move the downloaded .mar file into the `app-update` directory
1. Rename .mar file as `update.mar`
1. Open a `Terminal` and change directory into the Tor Browser installation (`cd /Applications/Tor\ Browser.app/`)
1. 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
1. `$ 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)
1. 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".
1. 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.
1. Open an un-elevated command prompt by {{{Win+R}}}, typing {{{cmd.exe}}} in the resulting prompt, and hitting the {{{OK}}} button.
1. 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.
1. Rename your downloaded MAR file to `update.mar`
1. Copy the {{{updater.exe}}} shipped with Tor Browser to your {{{app-update}}} directory:
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:
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.
