[tor-bugs] #13005 [Tor Browser]: Please document Tor Browser environment variables

[Tor Bug Tracker & Wiki]

#13005: Please document Tor Browser environment variables
-----------------------------+----------------------
     Reporter:  mttp         |      Owner:  tbb-team
         Type:  defect       |     Status:  new
     Priority:  normal       |  Milestone:
    Component:  Tor Browser  |    Version:
   Resolution:               |   Keywords:
Actual Points:               |  Parent ID:
       Points:               |
-----------------------------+----------------------

Comment (by mcs):

 Replying to [comment:3 mttp]:
 > Thanks for replying so quickly Mark. Some questions I still have:
 >
 > Does TOR_TRANSPROXY do anything that TOR_SKIP_LAUNCH doesn't do?

 They are different but related.  TOR_TRANSPROXY=1 enables Torbutton's
 transparent proxy mode, which is used if you have a Tor Router or some
 other set up that does not require that the browser connect to Tor via a
 SOCKS proxy.

 > Am I correct in thinking that you added a new environment variable
 recently to hide the Tor Logo if set to 1?

 Actually, that is only a build time option for Tor Launcher, not a run
 time option.  See ticket:12451#comment:3

 > Is the default value of TOR_CONTROL_PASSWD the empty string?

 Kind of.  If TOR_CONTROL_PASSWD is not set or if it is an empty string,
 Tor Launcher will generate a random password.

 > What is the default value of TOR_CONTROL_COOKIE_AUTH_FILE?

 There really isn't one.  Here is how things work in Tor Launcher:  if
 TOR_CONTROL_PASSWD is set, its value is used as the password.  If
 TOR_CONTROL_PASSWD is not set but TOR_CONTROL_COOKIE_AUTH_FILE is, then
 the cookie contained in the file that TOR_CONTROL_COOKIE_AUTH_FILE points
 to is used to authenticate to tor.  If neither one is set, a random
 password is generated and used.

 > I'm not sure I understand what you mean by "Also, Tor Launcher will not
 try to become the primary controller." in describing the
 TOR_CONFIGURE_ONLY option. Maybe I'm just unfamiliar the idea of a primary
 (versus secondary?) Tor controller.

 I may not using the correct terminology.  In the default situation
 (without TOR_CONFIGURE_ONLY and without TOR_SKIP_LAUNCH), Tor Launcher
 starts tor and then issues a TAKEOWNERSHIP command via tor's control port
 so that the tor process will automatically exit when Tor Launcher's
 control port connection is closed.  That way we have a much lower risk of
 an old tor process hanging around if the browser is killed or if it
 crashes.  But if TOR_CONFIGURE_ONLY=1 and also if TOR_SKIP_LAUNCH=1, Tor
 Launcher does not TAKEOWNERSHIP (the assumption being that if Tor Launcher
 did not start the tor process, it is someone else's problem to control its
 life cycle).

 Also possibly worth documenting:  there are hidden Firefox preferences
 that correspond to some of the env variables (but if an env variable is
 set, its corresponding pref is not consulted):

 {{{
 Env Variable Setting    Equivalent Pref Setting
 --------------------    -----------------------
 TOR_SKIP_LAUNCH=1       extensions.torlauncher.start_tor=false
 TOR_CONFIGURE_ONLY=1    extensions.torlauncher.only_configure_tor=true
 TOR_FORCE_NET_CONFIG=1  extensions.torlauncher.prompt_at_startup=true
 }}}

 The default for extensions.torlauncher.start_tor is true.

 The default for extensions.torlauncher.only_configure_tor is false.

 The initial value of extensions.torlauncher.prompt_at_startup is true but
 Tor Launcher automatically changes it to false after a successful Tor
 bootstrap, and automatically changes it to false after a failed bootstrap.
 So this one is not useful for people to set manually.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/13005#comment:4>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online