Opened 5 years ago

Last modified 9 months ago

#13005 needs_review enhancement

Please document Tor Browser environment variables

Reported by: mttp Owned by: traumschule
Priority: Medium Milestone:
Component: Community/Tor Browser Manual Version:
Severity: Normal Keywords: faq
Cc: tbb-team Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

It's not uncommon for users to want Tor Browser to use their already running system Tor. Doing this requires familiarity with the TOR_SKIP_LAUNCH environment variable. Rather than only documenting one or some of the env variables, they should all be documented in one place. Users should be able to visit a single document, FAQ entry, or wiki page where they can read the functionality of

TOR_SKIP_LAUNCH
TOR_FORCE_NET_CONFIG
TOR_CONFIGURE_ONLY
TOR_CONTROL_HOST
TOR_CONTROL_PORT
TOR_CONTROL_PASSWD
TOR_CONTROL_COOKIE_AUTH_FILE
TOR_SOCKS_HOST
TOR_SOCKS_PORT
TOR_TRANSPROXY

and how to set each. (Did I miss any?)

Child Tickets

Change History (11)

comment:1 Changed 5 years ago by mttp

TorBrowserBundle3SAQ is a good start. I asked arma whether the question on that page ought to be moved to the website FAQ, and he indicated his preference for more complete documentation of all Tor Browser's env variables.

Last edited 15 months ago by traumschule (previous) (diff)

comment:2 in reply to:  description ; Changed 5 years ago by mcs

Here is some info about the less commonly used env variables that are supported by Tor Launcher:

TOR_SKIP_LAUNCH - if set to 1, do not start a tor process, and, unless TOR_CONFIGURE_ONLY is set to 1, do to not try to configure Tor (that is, do not make a control port connection). Values other than 1 have no effect.

TOR_CONFIGURE_ONLY - if set to 1, do not start Tor but try to connect via the control port to configure Tor. Also, Tor Launcher will not try to become the primary controller. Values other than 1 have no effect.

TOR_FORCE_NET_CONFIG - if set to 1, display the Tor Network Settings wizard at startup (the value of the extensions.torlauncher.prompt_at_startup hidden preference is ignored). Values other than 1 have no effect. Used by Tails.

comment:3 in reply to:  2 ; Changed 5 years ago by mttp

Replying to mcs:

Here is some info about the less commonly used env variables that are supported by Tor Launcher:

TOR_SKIP_LAUNCH - if set to 1, do not start a tor process, and, unless TOR_CONFIGURE_ONLY is set to 1, do to not try to configure Tor (that is, do not make a control port connection). Values other than 1 have no effect.

TOR_CONFIGURE_ONLY - if set to 1, do not start Tor but try to connect via the control port to configure Tor. Also, Tor Launcher will not try to become the primary controller. Values other than 1 have no effect.

TOR_FORCE_NET_CONFIG - if set to 1, display the Tor Network Settings wizard at startup (the value of the extensions.torlauncher.prompt_at_startup hidden preference is ignored). Values other than 1 have no effect. Used by Tails.

Thanks for replying so quickly Mark. Some questions I still have:

Does TOR_TRANSPROXY do anything that TOR_SKIP_LAUNCH doesn't do?

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

Is the default value of TOR_CONTROL_PASSWD the empty string?

What is the default value of TOR_CONTROL_COOKIE_AUTH_FILE?

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.

Thanks in advance.

comment:4 in reply to:  3 Changed 5 years ago by mcs

Replying to 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.

comment:5 Changed 5 years ago by pragmatist

Hi I am writing this as a open letter/ request to the TBB team. Can you please consider designs like Whonix when adding functionality where Tor is run on a different machine than the one TBB is on and ControlPort access is prevented?

Tor's ControlPort has very rich functionality, some of which allows an adversary to pull off many dangerous and unwanted actions. Examples are: getting Tor to disclose the host's IP address, making Tor use an arbitrary relay or bridge, making Tor run as a Hidden service without the user's permission. The controlport filter mechanism that is being used by whonix and TAILS is not a great workaround because a skilled enough attacker (think NSA) probably has the 0days and knowledge to make bash or python do something unexpected when parsing malicious input. Ideally we would prefer simply not to allow any access to the ControlPort as the adversary cannot exploit what is not there.

The environment variable list is a good thing because it disables false positive warnings that Torbutton will issue otherwise when it isn't able to communicate with the controlport. Please consider not making any hard dependencies on ControlPort in your future development direction.

From what Roger said, the "get clockskew info" request is probably going to be implemented so that some controller running next to tor that learns the answer to stuff, and exports it somehow to the vm that has tor browser in. Sort of like the current ControlPort Filter idea but the other way around. this is good as long as nothing malicious like the actions described above are possible.

comment:6 Changed 2 years ago by teor

Severity: Normal

Set all open tickets without a severity to "Normal"

comment:7 Changed 15 months ago by traumschule

Component: Applications/Tor BrowserWebpages/Website
Keywords: faq added
Owner: changed from tbb-team to traumschule
Status: newassigned
Type: defectenhancement

If this is about the Website FAQ the component was wrong, otherwise: #27674

comment:8 Changed 15 months ago by traumschule

Status: assignedneeds_review

comment:9 Changed 14 months ago by traumschule

Cc: tbb-team added

Did anything change in the meantime?

comment:10 Changed 13 months ago by traumschule

Made some corrections and rebased. The wiki TorBrowserBundle3SAQ has been incorporated while TorBrowserBundleSAQ has more info that may be outdated. In that case it is maybe better to blank it? Unsure what to do about comment:5.

comment:11 Changed 9 months ago by emmapeel

Component: Webpages/WebsiteCommunity/Tor Browser Manual

maybe we should add it to the tb-manual?

Note: See TracTickets for help on using tickets.