A wireframe globe breaking out of chains

Free the internet

Support tools that break the chains of censorship and surveillance. Donate to the Tor Project today.

Donate now

Customizing `about:tor`

Development process

Here is how to test changes to about:tor, without having to rebuild Tor Browser or Tails.

However, please consider Building Tor Browser: it is actually pretty easy and once done once (for a given version), make && make run is a quicker & more convenient to way to iterate on about:tor contents and JS code changes than what's described below.

Initial setup

What follows assumes:

  • Your current working directory is the checkout of tor-browser.git that you are developing your changes in.
  • TAILS_GIT_REPO is set to the path to a checkout of tails.git.
  • TOR_BROWSER_TARBALL is set to the path to a Tor Browser tarball that you want to test your changes with.
  • sudo apt install 7zip

Modify files

These are the relevant files in tor-browser.git:

  • Page contents (HTML, JS, CSS, images):
    • ./browser/components/abouttor/content/
    • ./browser/components/abouttor/AboutTorParent.sys.mjs
  • User-visible strings
    • toolkit/locales/en-US/toolkit/global/tor-browser.ftl

You can test your changes like this:

"${TAILS_GIT_REPO:?}"/bin/test-about-tor-customization "${TOR_BROWSER_TARBALL:?}"

Submit your changes upstream

Contributing to Tor Browser: explains how to create issues and MRs, how to choose branch names, how to write commit messages, etc.

Tips and resources

  • To display contents under conditions that are more complex than "are we on Tails", e.g. during a specific time span, use potentiallyShow in aboutTor.js. Examples:

  • Localization