|
|
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):
|
|
|
- https://aus1.torproject.org/torbrowser/update_3/release/downloads.json
|
|
|
- https://aus1.torproject.org/torbrowser/update_3/alpha/downloads.json
|
|
|
|
|
|
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:
|
|
|
- https://aus1.torproject.org/torbrowser/update_3/alpha/Linux_x86_64-gcc3/9.5a2/en-US
|
|
|
|
|
|
When updating from a version of Tor Browser older than 8.0, due to the watershed the URL is something like:
|
|
|
- https://aus1.torproject.org/torbrowser/update_3/alpha/Linux_x86_64-gcc3/9.5a2/en-US
|
|
|
|
|
|
## 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 | 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:
|
|
|
- `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. |
|
|
\ No newline at end of file |