Skip to content
This repository has been archived by the owner on Jul 4, 2023. It is now read-only.

faq: explain TB environment variables (#13005) #49

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

faq: explain TB environment variables (#13005) #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 171 additions & 1 deletion docs/en/faq.wml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,10 @@
run another application through Tor.</a></li>
<li><a href="#CantSetProxy">What should I do if I can't set a proxy
with my application?</a></li>
<li><a href="#TBBUseOtherTor">How do I make Tor Browser use the tor that is
already running on the system?</a></li>
<li><a href="#TBBEnvVar">Which environment variables does Tor Launcher
respect?</a></li>
</ul>

<a id="tbb-3plus"></a>
Expand Down Expand Up @@ -1410,7 +1414,7 @@
First (best option), if you're on Linux, you can install the
<a href="<page download/download-unix>">system Tor package</a>
(e.g. apt-get install tor) and then set it up to be a relay
(<a href="https://www.torproject.org/docs/tor-relay-debian">instructions</a>).
(<a href="/docs/tor-relay-debian">instructions</a>).
You can then use TBB independent of that.
</p>

Expand All @@ -1427,6 +1431,172 @@

<hr>

<a id="TBBUseOtherTor"></a>
<h3><a class="anchor" href="#TBBUseOtherTor">
How do I make Tor Browser use the tor that is already running on the system?
</a></h3>

<p>
Are you sure you want to do this? The Tor Browser runs tor using different
ports so it can co-exist happily with the tor process already running on
your system. Furthermore if you are running a relay, it may be better to
run another tor instance for all of your personal Tor usage.
</p>

<p><strong>
Note: Using Tor Browser in this manner is <tt>NOT OFFICIALLY SUPPORTED</tt>.
<br/>
If this does not work or randomly clobbers your torrc, you are on your own.
</strong></p>

<p>
If you are using the Tor Project's
<a href="<page docs/debian>">Debian/Ubuntu packages</a>
(You ran <tt>apt-get install tor</tt> at some point):
</p>

<p>
Add the user you will be running Tor Browser as to the debian-tor group.
Set the following environment variables:
</p>

<pre>
export TOR_SKIP_LAUNCH=1
export TOR_SOCKS_PORT=9050
export TOR_CONTROL_PORT=9051
export TOR_CONTROL_COOKIE_AUTH_FILE=/var/run/tor/control.authcookie
</pre>

<p>
Start Tor Browser.
</p>

<pre>
$ ./start-tor-browser.sh
</pre>

<p>
If you wish to use password authentication for the control port,
you will need to wait till #9936 is fixed.
</p>

<hr/>

<a id="TBBEnvVar"></a>
<h3><a class="anchor" href="#TBBEnvVar">
Which environment variables does Tor Launcher respect?
</a></h3>

<p>
Following settings can be changed but be aware that this is
<strong>not recommended</strong> and can harm your anonymity.
</p>

<p>
In the default situation (without <tt>TOR_CONFIGURE_ONLY</tt> and without
<tt>TOR_SKIP_LAUNCH</tt>), 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 when <tt>TOR_CONFIGURE_ONLY=1</tt>
and <tt>TOR_SKIP_LAUNCH=1</tt> are set, 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).
</p>

<ul>
<li>
<tt>TOR_SKIP_LAUNCH</tt>:
if set to 1, do not start a tor process, and, unless
<tt>TOR_CONFIGURE_ONLY</tt> 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
<br/>(default: false)
</li>
<li>
<tt>TOR_CONFIGURE_ONLY</tt>:
if set to 1, do not start Tor but try to connect via the control
port to configure Tor. Tor Launcher will not try to become the primary
controller. Values other than 1 have no effect.
<br/>(default: false)
</li>
<li>
<tt>TOR_FORCE_NET_CONFIG</tt>:
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.
<br/>(default: false)
</li>
<li>
<tt>TOR_TRANSPROXY</tt>:
if set to 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.
<br/>(default: false)
</li>
<li>
<tt>TOR_CONTROL_PASSWD</tt>:
if this is not set or if it is an empty string, Tor Launcher will
generate a random password.
<br/>(default: empty)
</li>
<li>
<tt>TOR_CONTROL_COOKIE_AUTH_FILE</tt>:
if <tt>TOR_CONTROL_PASSWD</tt> is set, its value is used as the password.
If <tt>TOR_CONTROL_PASSWD</tt> is not set but
<tt>TOR_CONTROL_COOKIE_AUTH_FILE</tt> is, then the cookie contained in
the file that <tt>TOR_CONTROL_COOKIE_AUTH_FILE</tt> points to is used
to authenticate to tor. If neither one is set, a random password is
generated and used.
<br/>(default: empty)
</li>
<li>
<tt>TOR_CONTROL_HOST</tt>:
if set, it becomes part of the CONTROLPORT setting.
<br/>(default: 127.0.0.1)
</li>
<li>
<tt>TOR_CONTROL_PORT</tt>:
if set, it replaces the default CONTROLPORT.
<br/>(default: 9151)
</li>
<li>
<tt>TOR_SOCKS_HOST</tt>:
if set, it becomes part of the SOCKSPORT setting
<br/>(default: empty)
</li>
<li>
<tt>TOR_SOCKS_PORT</tt>:
if set, it replaces the default SOCKSPORT
<br/>(default: 9050)
</li>
</ul>

<p>
There are Firefox preferences that correspond to some of the environment
variables. If an env variable is set the equivalent preference setting is
overwritten:
</p>

<ul>
<li><tt>TOR_SKIP_LAUNCH=1</tt>:
extensions.torlauncher.start_tor=false (default: true)
</li>
<li><tt>TOR_CONFIGURE_ONLY=1</tt>:
extensions.torlauncher.only_configure_tor=true (default: false)
</li>
<li><tt>TOR_FORCE_NET_CONFIG=1</tt>:
extensions.torlauncher.prompt_at_startup=true (The default value of
<tt>extensions.torlauncher.prompt_at_startup</tt> 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 to set manually.)
</li>
</ul>

<hr/>

<a id="Timestamps"></a>
<h3><a class="anchor" href="#Timestamps">Why are the file timestamps
from 2000?</a></h3>
Expand Down
121 changes: 121 additions & 0 deletions docs/en/update_signing-keys.pl.withsig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
#!/usr/bin/env perl
use strict;
use warnings;

my $keysfile = "include/keys.txt";
my $wmifile = 'include/keys.wmi';
my $forcekeyupdates = 0;
my $skipkeyupdates = 0;

# First we load the keys, then we create a wmi file which is included by
# https://www.torproject.org/docs/signing-keys.html.en

# Determine the base directory in case we are called from somewhere else.
# We assume to sit in docs/en. Update $root path if this file has moved:
$0 =~ /^(.+)\/[^\/]+$/;
my $root = "$1/../..";
chdir $root or die "Could not enter $root: $! (script path: $0)\n";

open my $kf, '<', "$keysfile" # read keys
or die "Could not open $keysfile: $!\n";

my %sections; # project => key owners
my %owners; # key owner => string with all keys
my @projects; # save sections in order of appearance
my $section;
foreach (<$kf>) {
# filters comment and empty lines
next if ($_ eq "\n");
if (/^#/) {
# [section] / project
} elsif (/^\[(.+)\]$/) {
$section = "$1";
$sections{"$section"} = ();
push (@projects, $section);
# key owner with list of key id(s)
} elsif (/^([^:]+):(.+)$/) {
my $owner = "$1";
my $keys = "$2";
push( @{$sections{"$section"}}, $owner);
$owners{"$owner"} = "$keys";
# tell about unrecognized lines
} else { print "Ignored line: $_\n"; }
}
close $kf;
my @owners = keys %owners;
print "Loaded $keysfile. Found $#owners key owners in $#projects projects.\n";

# If the keysfile did not change since the last run, we will not update them.
# To update all keys anyway, set $forcekeyupdates = 1 above, or comment:
if (-f $wmifile && qx/[ $wmifile -nt $keysfile ]/) {
$forcekeyupdates or $skipkeyupdates++;
}

open my $out, '>', "$wmifile"
or die "Could not write to $wmifile; $!\n";
print $out "#!/usr/bin/env wml\n<p>
This page is automatically generated from
<a href='/include/keys.txt'>keys.txt</a> (<a href='/include/keys.txt.asc'>.asc</a>).
You can verify its signature as described in our
<a href='/docs/verifying-signatures.html'>manual to verify signatures</a>.
The signing keys we use are:\n</p>\n<ul>\n";
my %fingerprints;
foreach my $project (@projects) {
my $owners = '';
my $suf = 's';
my @keysinproject;
# we grab the key owners for each project and iterate over their keys
foreach my $owner (@{$sections{"$project"}}) { # iterate over owners
my $keys = $owners{"$owner"};
# example for $keys: 0x165733EA, 0x8D29319A(signing key)
my $inbrackets = '';
$suf = '' if ($owners ne '');
my @keys = split (',', $keys);
foreach my $key (@keys) { # iterate over keys
# validate key format. all regexp are beautiful.
if ($key =~ /^\s?(0x[^\(]+)(\(([^\)]+)\))?/) {
my $key = $1;
push (@keysinproject, $key);
# named alternative key
if ($2) {
$inbrackets .= " with its $3 $key";
# first key
} elsif ($inbrackets eq '') {
$inbrackets = "$key";
# second key
} else {
$inbrackets .= " and $key";
}
} else { # tell if the format is wrong
print "Unrecognized key format: $key\n";
}
}
my $sep = ($owners eq '') ? '' : ', ';
# Add owner to the list
$owners .= "$sep$owner ($inbrackets)";
print " - $owner ($inbrackets) [$project]\n";
}
if ($project eq 'other') {
print $out "<li>Other developers include $owners.</li>\n";
} else {
$suf = 'ed' if ($project =~ /older/);
print $out "<li>$owners sign$suf <strong>$project</strong></li>\n";
}
my $keyids = join (' ', @keysinproject);
# update keys form keyserver pool
if ($forcekeyupdates or not $skipkeyupdates) {
print "Fetching $keyids from keyserver:\n";
qx/gpg --recv-key $keyids/;
}
# save gpg output for later
my $str = qx/gpg --list-keys --keyid-format 0xlong --with-fingerprint $keyids/;
$str =~ s/</&lt;/g; $str =~ s/>/&gt;/g; $str =~ s/@/#/g; # replace html codes
$fingerprints{"$project"} = "<pre>\n$str</pre>\n";
}

# print keys for each project to file
print $out "</ul>\n<h2>Fingerprints</h2>\n<p>The fingerprints for the keys are:</p>\n";
foreach my $project (@projects) {
print $out "<h3>$project</h3>\n". $fingerprints{"$project"};
}
close $out; print "Wrote $wmifile.\n"; exit 0;