From 3e63ce3c71620433dc135959b2743aa010b28fe1 Mon Sep 17 00:00:00 2001 From: varac Date: Tue, 17 May 2016 12:52:57 +0200 Subject: update submodules so "rake test" doesnt complain anymore --- puppet/modules/tor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'puppet/modules/tor/files') diff --git a/puppet/modules/tor b/puppet/modules/tor index 8c936c16..9981a70f 160000 --- a/puppet/modules/tor +++ b/puppet/modules/tor @@ -1 +1 @@ -Subproject commit 8c936c166b6da1ebd0e8d95e56ceee5167357d63 +Subproject commit 9981a70f7ba1f9e4fe33e4eb46654295287c1fc1 -- cgit v1.2.3 From 7ce3190986cf8e5fe037a7ccd4c1076505b117f4 Mon Sep 17 00:00:00 2001 From: Micah Date: Tue, 12 Jul 2016 16:41:59 -0400 Subject: remove submodules in preparation for move to subrepos Change-Id: Ia7655153b556337f676e3d909559c4a7306bedd6 --- puppet/modules/tor | 1 - 1 file changed, 1 deletion(-) delete mode 160000 puppet/modules/tor (limited to 'puppet/modules/tor/files') diff --git a/puppet/modules/tor b/puppet/modules/tor deleted file mode 160000 index 9981a70f..00000000 --- a/puppet/modules/tor +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 9981a70f7ba1f9e4fe33e4eb46654295287c1fc1 -- cgit v1.2.3 From 297fadc8e6ad4729589d4ec21683f05a1e50bdf9 Mon Sep 17 00:00:00 2001 From: Micah Date: Tue, 12 Jul 2016 16:46:13 -0400 Subject: git subrepo clone https://leap.se/git/puppet_tor puppet/modules/tor subrepo: subdir: "puppet/modules/tor" merged: "9981a70" upstream: origin: "https://leap.se/git/puppet_tor" branch: "master" commit: "9981a70" git-subrepo: version: "0.3.0" origin: "https://github.com/ingydotnet/git-subrepo" commit: "1e79595" Change-Id: I0a876a52bd83914cfd1e06abe9af208dd62e5683 --- puppet/modules/tor/files/munin/tor_connections | 162 ++ puppet/modules/tor/files/munin/tor_routers | 151 ++ puppet/modules/tor/files/munin/tor_traffic | 154 ++ puppet/modules/tor/files/polipo/polipo.conf | 164 ++ puppet/modules/tor/files/tor-exit-notice.html | 144 ++ puppet/modules/tor/files/tor.html | 3157 ++++++++++++++++++++++++ 6 files changed, 3932 insertions(+) create mode 100755 puppet/modules/tor/files/munin/tor_connections create mode 100755 puppet/modules/tor/files/munin/tor_routers create mode 100755 puppet/modules/tor/files/munin/tor_traffic create mode 100644 puppet/modules/tor/files/polipo/polipo.conf create mode 100644 puppet/modules/tor/files/tor-exit-notice.html create mode 100644 puppet/modules/tor/files/tor.html (limited to 'puppet/modules/tor/files') diff --git a/puppet/modules/tor/files/munin/tor_connections b/puppet/modules/tor/files/munin/tor_connections new file mode 100755 index 00000000..c1d0a928 --- /dev/null +++ b/puppet/modules/tor/files/munin/tor_connections @@ -0,0 +1,162 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor +# +# Author: Ge van Geldorp +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +my %connections = ("new", 0, + "launched", 0, + "connected", 0, + "failed", 0, + "closed", 0); + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Connections\n"; + print "graph_args -l 0 --base 1000\n"; + print "graph_vlabel connections\n"; + print "graph_category Tor\n"; + print "graph_period second\n"; + print "graph_info This graph shows the number of Tor OR connections.\n"; + + foreach my $status (keys %connections) { + print "$status.label $status\n"; + print "$status.type GAUGE\n"; + print "$status.max 50000\n"; + print "$status.min 0\n"; + } + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "GETINFO orconn-status\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +while (! (($replyline = <$socket>) =~ /^\.\s*$/)) { + my @reply = split(/\s+/, $replyline); + $connections{lc($reply[1])}++; +} +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to authenticate: $replyline\n"; +} + +print $socket "QUIT\r\n"; +close($socket); + +while (my ($status, $count) = each(%connections)) { + print "$status.value $count\n"; +} + +exit 0; + +# vim:syntax=perl diff --git a/puppet/modules/tor/files/munin/tor_routers b/puppet/modules/tor/files/munin/tor_routers new file mode 100755 index 00000000..b977f9aa --- /dev/null +++ b/puppet/modules/tor/files/munin/tor_routers @@ -0,0 +1,151 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor routers +# +# Author: Ævar Arnfjörð Bjarmason , based on a plugin by Ge van Geldorp +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Routers\n"; + print "graph_args -l 0\n"; + print "graph_vlabel routers\n"; + print "graph_category Tor\n"; + print "graph_info This graph shows the number of known Tor ORs.\n"; + + print "ors.label routers\n"; + print "ors.type GAUGE\n"; + print "ors.info The number of known Tor ORs (onion routers)\n"; + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "GETINFO ns/all\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +my $count; +while (! (($replyline = <$socket>) =~ /^\.\s*$/)) { + my @reply = split(/\s+/, $replyline); + $count++ if $reply[0] eq 'r'; +} +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to authenticate: $replyline\n"; +} + +print $socket "QUIT\r\n"; +close($socket); + +print "ors.value $count\n"; + +exit 0; + +# vim:syntax=perl diff --git a/puppet/modules/tor/files/munin/tor_traffic b/puppet/modules/tor/files/munin/tor_traffic new file mode 100755 index 00000000..a72e7d7f --- /dev/null +++ b/puppet/modules/tor/files/munin/tor_traffic @@ -0,0 +1,154 @@ +#!/usr/bin/perl -w +# +# Munin plugin to monitor Tor traffic +# +# Author: Ge van Geldorp +# +# Parameters understood: +# +# host - Change which host to graph (default localhost) +# port - Change which port to connect to (default 9051) +# password - Plain-text control channel password (see torrc +# HashedControlPassword parameter) +# cookiefile - Name of the file containing the control channel cookie +# (see torrc CookieAuthentication parameter) +# +# Using HashedControlPassword authentication has the problem that you must +# include the plain-text password in the munin config file. To have any +# effect, that file shouldn't be world-readable. +# If you're using CookieAuthentication, you should run this plugin as a user +# which has read access to the tor datafiles. Also note that bugs in versions +# upto and including 0.1.1.20 prevent CookieAuthentication from working. +# +# Usage: place in /etc/munin/node.d/ (or link it there using ln -s) +# +# Parameters understood: +# config (required) +# autoconf (optional - used by munin-config) +# +# +# Magic markers - optional - used by installation scripts and +# munin-config: +# +#%# family=contrib +#%# capabilities=autoconf + +use strict; +use IO::Socket::INET; + +# Config +our $address = $ENV{host} || "localhost"; # Default: localhost +our $port = $ENV{port} || 9051; # Default: 9051 + +# Don't edit below this line + +sub Authenticate +{ + my ($socket) = @_; + my $authline = "AUTHENTICATE"; + if (defined($ENV{cookiefile})) { + if (open(COOKIE, "<$ENV{cookiefile}")) { + binmode COOKIE; + my $cookie; + $authline .= " "; + while (read(COOKIE, $cookie, 32)) { + foreach my $byte (unpack "C*", $cookie) { + $authline .= sprintf "%02x", $byte; + } + } + close COOKIE; + } + } elsif (defined($ENV{password})) { + $authline .= ' "' . $ENV{password} . '"'; + } + print $socket "$authline\r\n"; + my $replyline = <$socket>; + if (substr($replyline, 0, 1) != '2') { + $replyline =~ s/\s*$//; + return "Failed to authenticate: $replyline"; + } + + return; +} + +if ($ARGV[0] and $ARGV[0] eq "autoconf") { + # Try to connect to the daemon + my $socket = IO::Socket::INET->new("$address:$port") + or my $failed = 1; + + if ($failed) { + print "no (failed to connect to $address port $port)\n"; + exit 1; + } + + my $msg = Authenticate($socket); + if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + print "no ($msg)\n"; + exit 1; + } + + print $socket "QUIT\r\n"; + close($socket); + print "yes\n"; + exit 0; +} + +if ($ARGV[0] and $ARGV[0] eq "config") { + print "graph_title Traffic\n"; + print "graph_vlabel bytes per \${graph_period} read (-) / written (+)\n"; + print "graph_category Tor\n"; + print "graph_info This graph shows the bandwidth used by Tor.\n"; + + print "read.label byte/s\n"; + print "read.type GAUGE\n"; + print "read.graph no\n"; + print "read.max 10000000\n"; + print "write.label byte/s\n"; + print "write.type GAUGE\n"; + print "write.negative read\n"; + print "write.max 10000000\n"; + + exit 0; +} + +my $socket = IO::Socket::INET->new("$address:$port") + or die("Couldn't connect to $address port $port: $!"); + +my $msg = Authenticate($socket); +if (defined($msg)) { + print $socket "QUIT\r\n"; + close($socket); + die "$msg\n"; +} + +print $socket "SETEVENTS bw\r\n"; +my $replyline = <$socket>; +if (substr($replyline, 0, 1) != '2') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get orconn-status info: $replyline\n"; +} + +$replyline = <$socket>; +if (substr($replyline, 0, 1) != '6') { + print $socket "QUIT\r\n"; + close($socket); + $replyline =~ s/\s*$//; + die "Failed to get bw: $replyline\n"; +} +my @reply = split(/\s+/, $replyline); + +print $socket "SETEVENTS\r\n"; +$replyline = <$socket>; +print $socket "QUIT\r\n"; +close($socket); + +print "read.value $reply[2]\n"; +print "write.value $reply[3]\n"; + +exit 0; + +# vim:syntax=perl diff --git a/puppet/modules/tor/files/polipo/polipo.conf b/puppet/modules/tor/files/polipo/polipo.conf new file mode 100644 index 00000000..12b10c41 --- /dev/null +++ b/puppet/modules/tor/files/polipo/polipo.conf @@ -0,0 +1,164 @@ +# Polipo Configuration from https://svn.torproject.org/svn/torbrowser/trunk/build-scripts/config/polipo.conf +# Managed by puppet. + +### Basic configuration +### ******************* + +# Uncomment one of these if you want to allow remote clients to +# connect: + +# proxyAddress = "::0" # both IPv4 and IPv6 +# proxyAddress = "0.0.0.0" # IPv4 only + +proxyAddress = "127.0.0.1" +proxyPort = 8118 + +# If you do that, you'll want to restrict the set of hosts allowed to +# connect: + +# allowedClients = "127.0.0.1, 134.157.168.57" +# allowedClients = "127.0.0.1, 134.157.168.0/24" + +allowedClients = 127.0.0.1 +allowedPorts = 1-65535 + +# Uncomment this if you want your Polipo to identify itself by +# something else than the host name: + +proxyName = "localhost" + +# Uncomment this if there's only one user using this instance of Polipo: + +cacheIsShared = false + +# Uncomment this if you want to use a parent proxy: + +# parentProxy = "squid.example.org:3128" + +# Uncomment this if you want to use a parent SOCKS proxy: + +socksParentProxy = "localhost:9050" +socksProxyType = socks5 + + +### Memory +### ****** + +# Uncomment this if you want Polipo to use a ridiculously small amount +# of memory (a hundred C-64 worth or so): + +# chunkHighMark = 819200 +# objectHighMark = 128 + +# Uncomment this if you've got plenty of memory: + +# chunkHighMark = 50331648 +# objectHighMark = 16384 + +chunkHighMark = 67108864 + +### On-disk data +### ************ + +# Uncomment this if you want to disable the on-disk cache: + +diskCacheRoot = "" + +# Uncomment this if you want to put the on-disk cache in a +# non-standard location: + +# diskCacheRoot = "~/.polipo-cache/" + +# Uncomment this if you want to disable the local web server: + +localDocumentRoot = "" + +# Uncomment this if you want to enable the pages under /polipo/index? +# and /polipo/servers?. This is a serious privacy leak if your proxy +# is shared. + +# disableIndexing = false +# disableServersList = false + +disableLocalInterface = true +disableConfiguration = true + +### Domain Name System +### ****************** + +# Uncomment this if you want to contact IPv4 hosts only (and make DNS +# queries somewhat faster): +# +# dnsQueryIPv6 = no + +# Uncomment this if you want Polipo to prefer IPv4 to IPv6 for +# double-stack hosts: +# +# dnsQueryIPv6 = reluctantly + +# Uncomment this to disable Polipo's DNS resolver and use the system's +# default resolver instead. If you do that, Polipo will freeze during +# every DNS query: + +dnsUseGethostbyname = yes + + +### HTTP +### **** + +# Uncomment this if you want to enable detection of proxy loops. +# This will cause your hostname (or whatever you put into proxyName +# above) to be included in every request: + +disableVia = true + +# Uncomment this if you want to slightly reduce the amount of +# information that you leak about yourself: + +# censoredHeaders = from, accept-language +# censorReferer = maybe + +censoredHeaders = from,accept-language,x-pad,link +censorReferer = maybe + +# Uncomment this if you're paranoid. This will break a lot of sites, +# though: + +# censoredHeaders = set-cookie, cookie, cookie2, from, accept-language +# censorReferer = true + +# Uncomment this if you want to use Poor Man's Multiplexing; increase +# the sizes if you're on a fast line. They should each amount to a few +# seconds' worth of transfer; if pmmSize is small, you'll want +# pmmFirstSize to be larger. + +# Note that PMM is somewhat unreliable. + +# pmmFirstSize = 16384 +# pmmSize = 8192 + +# Uncomment this if your user-agent does something reasonable with +# Warning headers (most don't): + +# relaxTransparency = maybe + +# Uncomment this if you never want to revalidate instances for which +# data is available (this is not a good idea): + +# relaxTransparency = yes + +# Uncomment this if you have no network: + +# proxyOffline = yes + +# Uncomment this if you want to avoid revalidating instances with a +# Vary header (this is not a good idea): + +# mindlesslyCacheVary = true + +# Suggestions from Incognito configuration +maxConnectionAge = 5m +maxConnectionRequests = 120 +serverMaxSlots = 8 +serverSlots = 2 +tunnelAllowedPorts = 1-65535 diff --git a/puppet/modules/tor/files/tor-exit-notice.html b/puppet/modules/tor/files/tor-exit-notice.html new file mode 100644 index 00000000..de3be174 --- /dev/null +++ b/puppet/modules/tor/files/tor-exit-notice.html @@ -0,0 +1,144 @@ + + + + + +This is a Tor Exit Router + + + + + + +

This is a +Tor Exit Router

+ +

+Most likely you are accessing this website because you had some issue with +the traffic coming from this IP. This router is part of the Tor Anonymity Network, which is +dedicated to providing +privacy to people who need it most: average computer users. This +router IP should be generating no other traffic, unless it has been +compromised.

+ + + + +

+ +How Tor works +

+ +

+Tor sees use by many +important segments of the population, including whistle blowers, +journalists, Chinese dissidents skirting the Great Firewall and oppressive +censorship, abuse victims, stalker targets, the US military, and law +enforcement, just to name a few. While Tor is not designed for malicious +computer users, it is true that they can use the network for malicious ends. +In reality however, the actual amount of abuse is quite low. This +is largely because criminals and hackers have significantly better access to +privacy and anonymity than do the regular users whom they prey upon. Criminals +can and do build, +sell, and trade far larger and more +powerful networks than Tor on a daily basis. Thus, in the mind of this +operator, the social need for easily accessible censorship-resistant private, +anonymous communication trumps the risk of unskilled bad actors, who are +almost always more easily uncovered by traditional police work than by +extensive monitoring and surveillance anyway.

+ +

+In terms of applicable law, the best way to understand Tor is to consider it a +network of routers operating as common carriers, much like the Internet +backbone. However, unlike the Internet backbone routers, Tor routers +explicitly do not contain identifiable routing information about the source of +a packet, and no single Tor node can determine both the origin and destination +of a given transmission.

+ +

+As such, there is little the operator of this router can do to help you track +the connection further. This router maintains no logs of any of the Tor +traffic, so there is little that can be done to trace either legitimate or +illegitimate traffic (or to filter one from the other). Attempts to +seize this router will accomplish nothing.

+ + + +

+Furthermore, this machine also serves as a carrier of email, which means that +its contents are further protected under the ECPA. 18 +USC 2707 explicitly allows for civil remedies ($1000/account +plus legal fees) +in the event of a seizure executed without good faith or probable cause (it +should be clear at this point that traffic with an originating IP address of +FIXME_DNS_NAME should not constitute probable cause to seize the +machine). Similar considerations exist for 1st amendment content on this +machine.

+ + + +

+If you are a representative of a company who feels that this router is being +used to violate the DMCA, please be aware that this machine does not host or +contain any illegal content. Also be aware that network infrastructure +maintainers are not liable for the type of content that passes over their +equipment, in accordance with DMCA +"safe harbor" provisions. In other words, you will have just as much luck +sending a takedown notice to the Internet backbone providers. Please consult +EFF's prepared +response for more information on this matter.

+ +

For more information, please consult the following documentation:

+ +
    +
  1. Tor Overview
    2. +
  2. Tor Abuse FAQ
    3. +
  3. Tor Legal FAQ
    4. +
+ +

+That being said, if you still have a complaint about the router, you may +email the maintainer. If +complaints are related to a particular service that is being abused, I will +consider removing that service from my exit policy, which would prevent my +router from allowing that traffic to exit through it. I can only do this on an +IP+destination port basis, however. Common P2P ports are +already blocked.

+ +

+You also have the option of blocking this IP address and others on +the Tor network if you so desire. The Tor project provides a web service +to fetch a list of all IP addresses of Tor exit nodes that allow exiting to a +specified IP:port combination, and an official DNSRBL is also available to +determine if a given IP address is actually a Tor exit server. Please +be considerate +when using these options. It would be unfortunate to deny all Tor users access +to your site indefinitely simply because of a few bad apples.

+ + + diff --git a/puppet/modules/tor/files/tor.html b/puppet/modules/tor/files/tor.html new file mode 100644 index 00000000..484545b8 --- /dev/null +++ b/puppet/modules/tor/files/tor.html @@ -0,0 +1,3157 @@ + + + + + +TOR(1) + + + + +

SYNOPSIS

+
+

tor [OPTION value]…

+
+

DESCRIPTION

+
+

tor is a connection-oriented anonymizing communication +service. Users choose a source-routed path through a set of nodes, and +negotiate a "virtual circuit" through the network, in which each node +knows its predecessor and successor, but no others. Traffic flowing down +the circuit is unwrapped by a symmetric key at each node, which reveals +the downstream node.

+

Basically tor provides a distributed network of servers ("onion routers"). +Users bounce their TCP streams — web traffic, ftp, ssh, etc — around the +routers, and recipients, observers, and even the routers themselves have +difficulty tracking the source of the stream.

+
+

OPTIONS

+
+
+
+-h, -help +
+
+

+ Display a short help message and exit. +

+
+
+-f FILE +
+
+

+ FILE contains further "option value" pairs. (Default: /etc/tor/torrc) +

+
+
+--hash-password +
+
+

+ Generates a hashed password for control port access. +

+
+
+--list-fingerprint +
+
+

+ Generate your keys and output your nickname and fingerprint. +

+
+
+--verify-config +
+
+

+ Verify the configuration file is valid. +

+
+
+--nt-service +
+
+

+ --service [install|remove|start|stop] Manage the Tor Windows + NT/2000/XP service. Current instructions can be found at + https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#WinNTService +

+
+
+--list-torrc-options +
+
+

+ List all valid options. +

+
+
+--version +
+
+

+ Display Tor version and exit. +

+
+
+--quiet +
+
+

+ Do not start Tor with a console log unless explicitly requested to do so. + (By default, Tor starts out logging messages at level "notice" or higher to + the console, until it has parsed its configuration.) +

+
+
+

Other options can be specified either on the command-line (--option + value), or in the configuration file (option value or option "value"). + Options are case-insensitive. C-style escaped characters are allowed inside + quoted values. Options on the command line take precedence over + options found in the configuration file, except indicated otherwise. To + split one configuration entry into multiple lines, use a single \ before + the end of the line. Comments can be used in such multiline entries, but + they must start at the beginning of a line.

+
+
+BandwidthRate N bytes|KB|MB|GB +
+
+

+ A token bucket limits the average incoming bandwidth usage on this node to + the specified number of bytes per second, and the average outgoing + bandwidth usage to that same value. If you want to run a relay in the + public network, this needs to be at the very least 20 KB (that is, + 20480 bytes). (Default: 5 MB) +

+
+
+BandwidthBurst N bytes|KB|MB|GB +
+
+

+ Limit the maximum token bucket size (also known as the burst) to the given + number of bytes in each direction. (Default: 10 MB) +

+
+
+MaxAdvertisedBandwidth N bytes|KB|MB|GB +
+
+

+ If set, we will not advertise more than this amount of bandwidth for our + BandwidthRate. Server operators who want to reduce the number of clients + who ask to build circuits through them (since this is proportional to + advertised bandwidth rate) can thus reduce the CPU demands on their server + without impacting network performance. +

+
+
+RelayBandwidthRate N bytes|KB|MB|GB +
+
+

+ If not 0, a separate token bucket limits the average incoming bandwidth + usage for _relayed traffic_ on this node to the specified number of bytes + per second, and the average outgoing bandwidth usage to that same value. + Relayed traffic currently is calculated to include answers to directory + requests, but that may change in future versions. (Default: 0) +

+
+
+RelayBandwidthBurst N bytes|KB|MB|GB +
+
+

+ If not 0, limit the maximum token bucket size (also known as the burst) for + _relayed traffic_ to the given number of bytes in each direction. + (Default: 0) +

+
+
+PerConnBWRate N bytes|KB|MB|GB +
+
+

+ If set, do separate rate limiting for each connection from a non-relay. + You should never need to change this value, since a network-wide value is + published in the consensus and your relay will use that value. (Default: 0) +

+
+
+PerConnBWBurst N bytes|KB|MB|GB +
+
+

+ If set, do separate rate limiting for each connection from a non-relay. + You should never need to change this value, since a network-wide value is + published in the consensus and your relay will use that value. (Default: 0) +

+
+
+ConnLimit NUM +
+
+

+ The minimum number of file descriptors that must be available to the Tor + process before it will start. Tor will ask the OS for as many file + descriptors as the OS will allow (you can find this by "ulimit -H -n"). + If this number is less than ConnLimit, then Tor will refuse to start.
+
+ You probably don’t need to adjust this. It has no effect on Windows + since that platform lacks getrlimit(). (Default: 1000) +

+
+
+ConstrainedSockets 0|1 +
+
+

+ If set, Tor will tell the kernel to attempt to shrink the buffers for all + sockets to the size specified in ConstrainedSockSize. This is useful for + virtual servers and other environments where system level TCP buffers may + be limited. If you’re on a virtual server, and you encounter the "Error + creating network socket: No buffer space available" message, you are + likely experiencing this problem.
+
+ The preferred solution is to have the admin increase the buffer pool for + the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility; + this configuration option is a second-resort.
+
+ The DirPort option should also not be used if TCP buffers are scarce. The + cached directory requests consume additional sockets which exacerbates + the problem.
+
+ You should not enable this feature unless you encounter the "no buffer + space available" issue. Reducing the TCP buffers affects window size for + the TCP stream and will reduce throughput in proportion to round trip + time on long paths. (Default: 0.) +

+
+
+ConstrainedSockSize N bytes|KB +
+
+

+ When ConstrainedSockets is enabled the receive and transmit buffers for + all sockets will be set to this limit. Must be a value between 2048 and + 262144, in 1024 byte increments. Default of 8192 is recommended. +

+
+
+ControlPort PORT|auto +
+
+

+ If set, Tor will accept connections on this port and allow those + connections to control the Tor process using the Tor Control Protocol + (described in control-spec.txt). Note: unless you also specify one or + more of HashedControlPassword or CookieAuthentication, + setting this option will cause Tor to allow any process on the local + host to control it. (Setting both authentication methods means either + method is sufficient to authenticate to Tor.) This + option is required for many Tor controllers; most use the value of 9051. + Set it to "auto" to have Tor pick a port for you. (Default: 0). +

+
+
+ControlListenAddress IP[:PORT] +
+
+

+ Bind the controller listener to this address. If you specify a port, bind + to this port rather than the one specified in ControlPort. We strongly + recommend that you leave this alone unless you know what you’re doing, + since giving attackers access to your control listener is really + dangerous. (Default: 127.0.0.1) This directive can be specified multiple + times to bind to multiple addresses/ports. +

+
+
+ControlSocket Path +
+
+

+ Like ControlPort, but listens on a Unix domain socket, rather than a TCP + socket. (Unix and Unix-like systems only.) +

+
+
+ControlSocketsGroupWritable 0|1 +
+
+

+ If this option is set to 0, don’t allow the filesystem group to read and + write unix sockets (e.g. ControlSocket). If the option is set to 1, make + the control socket readable and writable by the default GID. (Default: 0) +

+
+
+HashedControlPassword hashed_password +
+
+

+ Allow connections on the control port if they present + the password whose one-way hash is hashed_password. You + can compute the hash of a password by running "tor --hash-password + password". You can provide several acceptable passwords by using more + than one HashedControlPassword line. +

+
+
+CookieAuthentication 0|1 +
+
+

+ If this option is set to 1, allow connections on the control port + when the connecting process knows the contents of a file named + "control_auth_cookie", which Tor will create in its data directory. This + authentication method should only be used on systems with good filesystem + security. (Default: 0) +

+
+
+CookieAuthFile Path +
+
+

+ If set, this option overrides the default location and file name + for Tor’s cookie file. (See CookieAuthentication above.) +

+
+
+CookieAuthFileGroupReadable 0|1|Groupname +
+
+

+ If this option is set to 0, don’t allow the filesystem group to read the + cookie file. If the option is set to 1, make the cookie file readable by + the default GID. [Making the file readable by other groups is not yet + implemented; let us know if you need this for some reason.] (Default: 0). +

+
+
+ControlPortWriteToFile Path +
+
+

+ If set, Tor writes the address and port of any control port it opens to + this address. Usable by controllers to learn the actual control port + when ControlPort is set to "auto". +

+
+
+ControlPortFileGroupReadable 0|1 +
+
+

+ If this option is set to 0, don’t allow the filesystem group to read the + control port file. If the option is set to 1, make the control port + file readable by the default GID. (Default: 0). +

+
+
+DataDirectory DIR +
+
+

+ Store working data in DIR (Default: /var/lib/tor) +

+
+
+DirServer [nickname] [flags] address:port fingerprint +
+
+

+ Use a nonstandard authoritative directory server at the provided address + and port, with the specified key fingerprint. This option can be repeated + many times, for multiple authoritative directory servers. Flags are + separated by spaces, and determine what kind of an authority this directory + is. By default, every authority is authoritative for current ("v2")-style + directories, unless the "no-v2" flag is given. If the "v1" flags is + provided, Tor will use this server as an authority for old-style (v1) + directories as well. (Only directory mirrors care about this.) Tor will + use this server as an authority for hidden service information if the "hs" + flag is set, or if the "v1" flag is set and the "no-hs" flag is not set. + Tor will use this authority as a bridge authoritative directory if the + "bridge" flag is set. If a flag "orport=port" is given, Tor will use the + given port when opening encrypted tunnels to the dirserver. Lastly, if a + flag "v3ident=fp" is given, the dirserver is a v3 directory authority + whose v3 long-term signing key has the fingerprint fp.
+
+ If no dirserver line is given, Tor will use the default directory + servers. NOTE: this option is intended for setting up a private Tor + network with its own directory authorities. If you use it, you will be + distinguishable from other users, because you won’t believe the same + authorities they do. +

+
+
+

AlternateDirAuthority [nickname] [flags] address:port fingerprint

+

AlternateHSAuthority [nickname] [flags] address:port fingerprint

+
+
+AlternateBridgeAuthority [nickname] [flags] address:port fingerprint +
+
+

+ As DirServer, but replaces less of the default directory authorities. Using + AlternateDirAuthority replaces the default Tor directory authorities, but + leaves the hidden service authorities and bridge authorities in place. + Similarly, Using AlternateHSAuthority replaces the default hidden service + authorities, but not the directory or bridge authorities. +

+
+
+DisableAllSwap 0|1 +
+
+

+ If set to 1, Tor will attempt to lock all current and future memory pages, + so that memory cannot be paged out. Windows, OS X and Solaris are currently + not supported. We believe that this feature works on modern Gnu/Linux + distributions, and that it should work on *BSD systems (untested). This + option requires that you start your Tor as root, and you should use the + User option to properly reduce Tor’s privileges. (Default: 0) +

+
+
+FetchDirInfoEarly 0|1 +
+
+

+ If set to 1, Tor will always fetch directory information like other + directory caches, even if you don’t meet the normal criteria for fetching + early. Normal users should leave it off. (Default: 0) +

+
+
+FetchDirInfoExtraEarly 0|1 +
+
+

+ If set to 1, Tor will fetch directory information before other directory + caches. It will attempt to download directory information closer to the + start of the consensus period. Normal users should leave it off. + (Default: 0) +

+
+
+FetchHidServDescriptors 0|1 +
+
+

+ If set to 0, Tor will never fetch any hidden service descriptors from the + rendezvous directories. This option is only useful if you’re using a Tor + controller that handles hidden service fetches for you. (Default: 1) +

+
+
+FetchServerDescriptors 0|1 +
+
+

+ If set to 0, Tor will never fetch any network status summaries or server + descriptors from the directory servers. This option is only useful if + you’re using a Tor controller that handles directory fetches for you. + (Default: 1) +

+
+
+FetchUselessDescriptors 0|1 +
+
+

+ If set to 1, Tor will fetch every non-obsolete descriptor from the + authorities that it hears about. Otherwise, it will avoid fetching useless + descriptors, for example for routers that are not running. This option is + useful if you’re using the contributed "exitlist" script to enumerate Tor + nodes that exit to certain addresses. (Default: 0) +

+
+
+HTTPProxy host[:port] +
+
+

+ Tor will make all its directory requests through this host:port (or host:80 + if port is not specified), rather than connecting directly to any directory + servers. +

+
+
+HTTPProxyAuthenticator username:password +
+
+

+ If defined, Tor will use this username:password for Basic HTTP proxy + authentication, as in RFC 2617. This is currently the only form of HTTP + proxy authentication that Tor supports; feel free to submit a patch if you + want it to support others. +

+
+
+HTTPSProxy host[:port] +
+
+

+ Tor will make all its OR (SSL) connections through this host:port (or + host:443 if port is not specified), via HTTP CONNECT rather than connecting + directly to servers. You may want to set FascistFirewall to restrict + the set of ports you might try to connect to, if your HTTPS proxy only + allows connecting to certain ports. +

+
+
+HTTPSProxyAuthenticator username:password +
+
+

+ If defined, Tor will use this username:password for Basic HTTPS proxy + authentication, as in RFC 2617. This is currently the only form of HTTPS + proxy authentication that Tor supports; feel free to submit a patch if you + want it to support others. +

+
+
+Socks4Proxy host[:port] +
+
+

+ Tor will make all OR connections through the SOCKS 4 proxy at host:port + (or host:1080 if port is not specified). +

+
+
+Socks5Proxy host[:port] +
+
+

+ Tor will make all OR connections through the SOCKS 5 proxy at host:port + (or host:1080 if port is not specified). +

+
+
+

Socks5ProxyUsername username

+
+
+Socks5ProxyPassword password +
+
+

+ If defined, authenticate to the SOCKS 5 server using username and password + in accordance to RFC 1929. Both username and password must be between 1 and + 255 characters. +

+
+
+KeepalivePeriod NUM +
+
+

+ To keep firewalls from expiring connections, send a padding keepalive cell + every NUM seconds on open connections that are in use. If the connection + has no open circuits, it will instead be closed after NUM seconds of + idleness. (Default: 5 minutes) +

+
+
+Log minSeverity[-maxSeverity] stderr|stdout|syslog +
+
+

+ Send all messages between minSeverity and maxSeverity to the standard + output stream, the standard error stream, or to the system log. (The + "syslog" value is only supported on Unix.) Recognized severity levels are + debug, info, notice, warn, and err. We advise using "notice" in most cases, + since anything more verbose may provide sensitive information to an + attacker who obtains the logs. If only one severity level is given, all + messages of that level or higher will be sent to the listed destination. +

+
+
+Log minSeverity[-maxSeverity] file FILENAME +
+
+

+ As above, but send log messages to the listed filename. The + "Log" option may appear more than once in a configuration file. + Messages are sent to all the logs that match their severity + level. +

+
+
+

Log [domain,…]minSeverity[-maxSeverity] … file FILENAME

+
+
+Log [domain,…]minSeverity[-maxSeverity] … stderr|stdout|syslog +
+
+

+ As above, but select messages by range of log severity and by a + set of "logging domains". Each logging domain corresponds to an area of + functionality inside Tor. You can specify any number of severity ranges + for a single log statement, each of them prefixed by a comma-separated + list of logging domains. You can prefix a domain with ~ to indicate + negation, and use * to indicate "all domains". If you specify a severity + range without a list of domains, it matches all domains.
+
+ This is an advanced feature which is most useful for debugging one or two + of Tor’s subsystems at a time.
+
+ The currently recognized domains are: general, crypto, net, config, fs, + protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge, + acct, hist, and handshake. Domain names are case-insensitive.
+
+ For example, "Log [handshake]debug [~net,~mm]info notice stdout" sends + to stdout: all handshake messages of any severity, all info-and-higher + messages from domains other than networking and memory management, and all + messages of severity notice or higher. +

+
+
+LogMessageDomains 0|1 +
+
+

+ If 1, Tor includes message domains with each log message. Every log + message currently has at least one domain; most currently have exactly + one. This doesn’t affect controller log messages. (Default: 0) +

+
+
+OutboundBindAddress IP +
+
+

+ Make all outbound connections originate from the IP address specified. This + is only useful when you have multiple network interfaces, and you want all + of Tor’s outgoing connections to use a single one. This setting will be + ignored for connections to the loopback addresses (127.0.0.0/8 and ::1). +

+
+
+PidFile FILE +
+
+

+ On startup, write our PID to FILE. On clean shutdown, remove + FILE. +

+
+
+ProtocolWarnings 0|1 +
+
+

+ If 1, Tor will log with severity 'warn' various cases of other parties not + following the Tor specification. Otherwise, they are logged with severity + 'info'. (Default: 0) +

+
+
+RunAsDaemon 0|1 +
+
+

+ If 1, Tor forks and daemonizes to the background. This option has no effect + on Windows; instead you should use the --service command-line option. + (Default: 0) +

+
+
+SafeLogging 0|1|relay +
+
+

+ Tor can scrub potentially sensitive strings from log messages (e.g. + addresses) by replacing them with the string [scrubbed]. This way logs can + still be useful, but they don’t leave behind personally identifying + information about what sites a user might have visited.
+
+ If this option is set to 0, Tor will not perform any scrubbing, if it is + set to 1, all potentially sensitive strings are replaced. If it is set to + relay, all log messages generated when acting as a relay are sanitized, but + all messages generated when acting as a client are not. (Default: 1) +

+
+
+User UID +
+
+

+ On startup, setuid to this user and setgid to their primary group. +

+
+
+HardwareAccel 0|1 +
+
+

+ If non-zero, try to use built-in (static) crypto hardware acceleration when + available. (Default: 0) +

+
+
+AccelName NAME +
+
+

+ When using OpenSSL hardware crypto acceleration attempt to load the dynamic + engine of this name. This must be used for any dynamic hardware engine. + Names can be verified with the openssl engine command. +

+
+
+AccelDir DIR +
+
+

+ Specify this option if using dynamic hardware acceleration and the engine + implementation library resides somewhere other than the OpenSSL default. +

+
+
+AvoidDiskWrites 0|1 +
+
+

+ If non-zero, try to write to disk less frequently than we would otherwise. + This is useful when running on flash memory or other media that support + only a limited number of writes. (Default: 0) +

+
+
+TunnelDirConns 0|1 +
+
+

+ If non-zero, when a directory server we contact supports it, we will build + a one-hop circuit and make an encrypted connection via its ORPort. + (Default: 1) +

+
+
+PreferTunneledDirConns 0|1 +
+
+

+ If non-zero, we will avoid directory servers that don’t support tunneled + directory connections, when possible. (Default: 1) +

+
+
+CircuitPriorityHalflife NUM1 +
+
+

+ If this value is set, we override the default algorithm for choosing which + circuit’s cell to deliver or relay next. When the value is 0, we + round-robin between the active circuits on a connection, delivering one + cell from each in turn. When the value is positive, we prefer delivering + cells from whichever connection has the lowest weighted cell count, where + cells are weighted exponentially according to the supplied + CircuitPriorityHalflife value (in seconds). If this option is not set at + all, we use the behavior recommended in the current consensus + networkstatus. This is an advanced option; you generally shouldn’t have + to mess with it. (Default: not set.) +

+
+
+
+

CLIENT OPTIONS

+
+

The following options are useful only for clients (that is, if +SocksPort is non-zero):

+
+
+AllowInvalidNodes entry|exit|middle|introduction|rendezvous|… +
+
+

+ If some Tor servers are obviously not working right, the directory + authorities can manually mark them as invalid, meaning that it’s not + recommended you use them for entry or exit positions in your circuits. You + can opt to use them in some circuit positions, though. The default is + "middle,rendezvous", and other choices are not advised. +

+
+
+ExcludeSingleHopRelays 0|1 +
+
+

+ This option controls whether circuits built by Tor will include relays with + the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set + to 0, these relays will be included. Note that these relays might be at + higher risk of being seized or observed, so they are not normally + included. Also note that relatively few clients turn off this option, + so using these relays might make your client stand out. + (Default: 1) +

+
+
+Bridge IP:ORPort [fingerprint] +
+
+

+ When set along with UseBridges, instructs Tor to use the relay at + "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" + is provided (using the same format as for DirServer), we will verify that + the relay running at that location has the right fingerprint. We also use + fingerprint to look up the bridge descriptor at the bridge authority, if + it’s provided and if UpdateBridgesFromAuthority is set too. +

+
+
+LearnCircuitBuildTimeout 0|1 +
+
+

+ If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) +

+
+
+CircuitBuildTimeout NUM +
+
+

+ Try for at most NUM seconds when building circuits. If the circuit isn’t + open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this + value serves as the initial value to use before a timeout is learned. If + LearnCircuitBuildTimeout is 0, this value is the only value used. + (Default: 60 seconds.) +

+
+
+CircuitIdleTimeout NUM +
+
+

+ If we have kept a clean (never used) circuit around for NUM seconds, then + close it. This way when the Tor client is entirely idle, it can expire all + of its circuits, and then expire its TLS connections. Also, if we end up + making a circuit that is not useful for exiting any of the requests we’re + receiving, it won’t forever take up a slot in the circuit list. (Default: 1 + hour.) +

+
+
+CircuitStreamTimeout NUM +
+
+

+ If non-zero, this option overrides our internal timeout schedule for how + many seconds until we detach a stream from a circuit and try a new circuit. + If your network is particularly slow, you might want to set this to a + number like 60. (Default: 0) +

+
+
+ClientOnly 0|1 +
+
+

+ If set to 1, Tor will under no circumstances run as a server or serve + directory requests. The default is to run as a client unless ORPort is + configured. (Usually, you don’t need to set this; Tor is pretty smart at + figuring out whether you are reliable and high-bandwidth enough to be a + useful server.) (Default: 0) +

+
+
+ExcludeNodes node,node,… +
+
+

+ A list of identity fingerprints, nicknames, country codes and address + patterns of nodes to avoid when building a circuit. + (Example: + ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc}, 255.254.0.0/8)
+
+ By default, this option is treated as a preference that Tor is allowed + to override in order to keep working. + For example, if you try to connect to a hidden service, + but you have excluded all of the hidden service’s introduction points, + Tor will connect to one of them anyway. If you do not want this + behavior, set the StrictNodes option (documented below).
+
+ Note also that if you are a relay, this (and the other node selection + options below) only affects your own circuits that Tor builds for you. + Clients can still build circuits through you to any node. Controllers + can tell Tor to build circuits through any node. +

+
+
+ExcludeExitNodes node,node,… +
+
+

+ A list of identity fingerprints, nicknames, country codes and address + patterns of nodes to never use when picking an exit node---that is, a + node that delivers traffic for you outside the Tor network. Note that any + node listed in ExcludeNodes is automatically considered to be part of this + list too. See also the caveats on the "ExitNodes" option below. +

+
+
+ExitNodes node,node,… +
+
+

+ A list of identity fingerprints, nicknames, country codes and address + patterns of nodes to use as exit node---that is, a + node that delivers traffic for you outside the Tor network.
+
+ Note that if you list too few nodes here, or if you exclude too many exit + nodes with ExcludeExitNodes, you can degrade functionality. For example, + if none of the exits you list allows traffic on port 80 or 443, you won’t + be able to browse the web.
+
+ Note also that not every circuit is used to deliver traffic outside of + the Tor network. It is normal to see non-exit circuits (such as those + used to connect to hidden services, those that do directory fetches, + those used for relay reachability self-tests, and so on) that end + at a non-exit node. To + keep a node from being used entirely, see ExcludeNodes and StrictNodes.
+
+ The ExcludeNodes option overrides this option: any node listed in both + ExitNodes and ExcludeNodes is treated as excluded.
+
+ The .exit address notation, if enabled via AllowDotExit, overrides + this option. +

+
+
+EntryNodes node,node,… +
+
+

+ A list of identity fingerprints and nicknames of nodes + to use for the first hop in your normal circuits. (Country codes and + address patterns are not yet supported.) Normal circuits include all + circuits except for direct connections to directory servers. The Bridge + option overrides this option; if you have configured bridges and + UseBridges is 1, the Bridges are used as your entry nodes.
+
+ The ExcludeNodes option overrides this option: any node listed in both + EntryNodes and ExcludeNodes is treated as excluded. +

+
+
+StrictNodes 0|1 +
+
+

+ If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a + requirement to follow for all the circuits you generate, even if doing so + will break functionality for you. If StrictNodes is set to 0, Tor will + still try to avoid nodes in the ExcludeNodes list, but it will err on the + side of avoiding unexpected errors. Specifically, StrictNodes 0 tells + Tor that it is okay to use an excluded node when it is necessary to + perform relay reachability self-tests, connect to + a hidden service, provide a hidden service to a client, fulfill a .exit + request, upload directory information, or download directory information. + (Default: 0) +

+
+
+FascistFirewall 0|1 +
+
+

+ If 1, Tor will only create outgoing connections to ORs running on ports + that your firewall allows (defaults to 80 and 443; see FirewallPorts). + This will allow you to run Tor as a client behind a firewall with + restrictive policies, but will not allow you to run as a server behind such + a firewall. If you prefer more fine-grained control, use + ReachableAddresses instead. +

+
+
+FirewallPorts PORTS +
+
+

+ A list of ports that your firewall allows you to connect to. Only used when + FascistFirewall is set. This option is deprecated; use ReachableAddresses + instead. (Default: 80, 443) +

+
+
+HidServAuth onion-address auth-cookie [service-name] +
+
+

+ Client authorization for a hidden service. Valid onion addresses contain 16 + characters in a-z2-7 plus ".onion", and valid auth cookies contain 22 + characters in A-Za-z0-9+/. The service name is only used for internal + purposes, e.g., for Tor controllers. This option may be used multiple times + for different hidden services. If a hidden service uses authorization and + this option is not set, the hidden service is not accessible. Hidden + services can be configured to require authorization using the + HiddenServiceAuthorizeClient option. +

+
+
+ReachableAddresses ADDR[/MASK][:PORT]… +
+
+

+ A comma-separated list of IP addresses and ports that your firewall allows + you to connect to. The format is as for the addresses in ExitPolicy, except + that "accept" is understood unless "reject" is explicitly provided. For + example, 'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept + *:80' means that your firewall allows connections to everything inside net + 99, rejects port 80 connections to net 18, and accepts connections to port + 80 otherwise. (Default: 'accept *:*'.) +

+
+
+ReachableDirAddresses ADDR[/MASK][:PORT]… +
+
+

+ Like ReachableAddresses, a list of addresses and ports. Tor will obey + these restrictions when fetching directory information, using standard HTTP + GET requests. If not set explicitly then the value of + ReachableAddresses is used. If HTTPProxy is set then these + connections will go through that proxy. +

+
+
+ReachableORAddresses ADDR[/MASK][:PORT]… +
+
+

+ Like ReachableAddresses, a list of addresses and ports. Tor will obey + these restrictions when connecting to Onion Routers, using TLS/SSL. If not + set explicitly then the value of ReachableAddresses is used. If + HTTPSProxy is set then these connections will go through that proxy.
+
+ The separation between ReachableORAddresses and + ReachableDirAddresses is only interesting when you are connecting + through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit + TLS connections (which Tor uses to connect to Onion Routers) to port 443, + and some limit HTTP GET requests (which Tor uses for fetching directory + information) to port 80. +

+
+
+LongLivedPorts PORTS +
+
+

+ A list of ports for services that tend to have long-running connections + (e.g. chat and interactive shells). Circuits for streams that use these + ports will contain only high-uptime nodes, to reduce the chance that a node + will go down before the stream is finished. (Default: 21, 22, 706, 1863, + 5050, 5190, 5222, 5223, 6667, 6697, 8300) +

+
+
+MapAddress address newaddress +
+
+

+ When a request for address arrives to Tor, it will rewrite it to newaddress + before processing it. For example, if you always want connections to + www.indymedia.org to exit via torserver (where torserver is the + nickname of the server), use "MapAddress www.indymedia.org + www.indymedia.org.torserver.exit". +

+
+
+NewCircuitPeriod NUM +
+
+

+ Every NUM seconds consider whether to build a new circuit. (Default: 30 + seconds) +

+
+
+MaxCircuitDirtiness NUM +
+
+

+ Feel free to reuse a circuit that was first used at most NUM seconds ago, + but never attach a new stream to a circuit that is too old. (Default: 10 + minutes) +

+
+
+NodeFamily node,node,… +
+
+

+ The Tor servers, defined by their identity fingerprints or nicknames, + constitute a "family" of similar or co-administered servers, so never use + any two of them in the same circuit. Defining a NodeFamily is only needed + when a server doesn’t list the family itself (with MyFamily). This option + can be used multiple times. +

+
+
+EnforceDistinctSubnets 0|1 +
+
+

+ If 1, Tor will not put two servers whose IP addresses are "too close" on + the same circuit. Currently, two addresses are "too close" if they lie in + the same /16 range. (Default: 1) +

+
+
+SocksPort PORT|auto +
+
+

+ Advertise this port to listen for connections from Socks-speaking + applications. Set this to 0 if you don’t want to allow application + connections via SOCKS. Set it to "auto" to have Tor pick a port for + you. (Default: 9050) +

+
+
+SocksListenAddress IP[:PORT] +
+
+

+ Bind to this address to listen for connections from Socks-speaking + applications. (Default: 127.0.0.1) You can also specify a port (e.g. + 192.168.0.1:9100). This directive can be specified multiple times to bind + to multiple addresses/ports. +

+
+
+SocksPolicy policy,policy,… +
+
+

+ Set an entrance policy for this server, to limit who can connect to the + SocksPort and DNSPort ports. The policies have the same form as exit + policies below. +

+
+
+SocksTimeout NUM +
+
+

+ Let a socks connection wait NUM seconds handshaking, and NUM seconds + unattached waiting for an appropriate circuit, before we fail it. (Default: + 2 minutes.) +

+
+
+TrackHostExits host,.domain,… +
+
+

+ For each value in the comma separated list, Tor will track recent + connections to hosts that match this value and attempt to reuse the same + exit node for each. If the value is prepended with a '.', it is treated as + matching an entire domain. If one of the values is just a '.', it means + match everything. This option is useful if you frequently connect to sites + that will expire all your authentication cookies (i.e. log you out) if + your IP address changes. Note that this option does have the disadvantage + of making it more clear that a given history is associated with a single + user. However, most people who would wish to observe this will observe it + through cookies or other protocol-specific means anyhow. +

+
+
+TrackHostExitsExpire NUM +
+
+

+ Since exit servers go up and down, it is desirable to expire the + association between host and exit server after NUM seconds. The default is + 1800 seconds (30 minutes). +

+
+
+UpdateBridgesFromAuthority 0|1 +
+
+

+ When set (along with UseBridges), Tor will try to fetch bridge descriptors + from the configured bridge authorities when feasible. It will fall back to + a direct request if the authority responds with a 404. (Default: 0) +

+
+
+UseBridges 0|1 +
+
+

+ When set, Tor will fetch descriptors for each bridge listed in the "Bridge" + config lines, and use these relays as both entry guards and directory + guards. (Default: 0) +

+
+
+UseEntryGuards 0|1 +
+
+

+ If this option is set to 1, we pick a few long-term entry servers, and try + to stick with them. This is desirable because constantly changing servers + increases the odds that an adversary who owns some servers will observe a + fraction of your paths. (Defaults to 1.) +

+
+
+NumEntryGuards NUM +
+
+

+ If UseEntryGuards is set to 1, we will try to pick a total of NUM routers + as long-term entries for our circuits. (Defaults to 3.) +

+
+
+SafeSocks 0|1 +
+
+

+ When this option is enabled, Tor will reject application connections that + use unsafe variants of the socks protocol — ones that only provide an IP + address, meaning the application is doing a DNS resolve first. + Specifically, these are socks4 and socks5 when not doing remote DNS. + (Defaults to 0.) +

+
+
+TestSocks 0|1 +
+
+

+ When this option is enabled, Tor will make a notice-level log entry for + each connection to the Socks port indicating whether the request used a + safe socks protocol or an unsafe one (see above entry on SafeSocks). This + helps to determine whether an application using Tor is possibly leaking + DNS requests. (Default: 0) +

+
+
+WarnUnsafeSocks 0|1 +
+
+

+ When this option is enabled, Tor will warn whenever a request is + received that only contains an IP address instead of a hostname. Allowing + applications to do DNS resolves themselves is usually a bad idea and + can leak your location to attackers. (Default: 1) +

+
+
+VirtualAddrNetwork Address/bits +
+
+

+ When Tor needs to assign a virtual (unused) address because of a MAPADDRESS + command from the controller or the AutomapHostsOnResolve feature, Tor + picks an unassigned address from this range. (Default: + 127.192.0.0/10)
+
+ When providing proxy server service to a network of computers using a tool + like dns-proxy-tor, change this address to "10.192.0.0/10" or + "172.16.0.0/12". The default VirtualAddrNetwork address range on a + properly configured machine will route to the loopback interface. For + local use, no change to the default VirtualAddrNetwork setting is needed. +

+
+
+AllowNonRFC953Hostnames 0|1 +
+
+

+ When this option is disabled, Tor blocks hostnames containing illegal + characters (like @ and :) rather than sending them to an exit node to be + resolved. This helps trap accidental attempts to resolve URLs and so on. + (Default: 0) +

+
+
+AllowDotExit 0|1 +
+
+

+ If enabled, we convert "www.google.com.foo.exit" addresses on the + SocksPort/TransPort/NATDPort into "www.google.com" addresses that exit from + the node "foo". Disabled by default since attacking websites and exit + relays can use it to manipulate your path selection. (Default: 0) +

+
+
+FastFirstHopPK 0|1 +
+
+

+ When this option is disabled, Tor uses the public key step for the first + hop of creating circuits. Skipping it is generally safe since we have + already used TLS to authenticate the relay and to establish forward-secure + keys. Turning this option off makes circuit building slower.
+
+ Note that Tor will always use the public key step for the first hop if it’s + operating as a relay, and it will never use the public key step if it + doesn’t yet know the onion key of the first hop. (Default: 1) +

+
+
+TransPort PORT|auto +
+
+

+ If non-zero, enables transparent proxy support on PORT (by convention, + 9040). Requires OS support for transparent proxies, such as BSDs' pf or + Linux’s IPTables. If you’re planning to use Tor as a transparent proxy for + a network, you’ll want to examine and change VirtualAddrNetwork from the + default setting. You’ll also want to set the TransListenAddress option for + the network you’d like to proxy. Set it to "auto" to have Tor pick a + port for you. (Default: 0). +

+
+
+TransListenAddress IP[:PORT] +
+
+

+ Bind to this address to listen for transparent proxy connections. (Default: + 127.0.0.1). This is useful for exporting a transparent proxy server to an + entire network. +

+
+
+NATDPort PORT|auto +
+
+

+ Allow old versions of ipfw (as included in old versions of FreeBSD, etc.) + to send connections through Tor using the NATD protocol. This option is + only for people who cannot use TransPort. Set it to "auto" to have Tor + pick a port for you. (Default: 0) +

+
+
+NATDListenAddress IP[:PORT] +
+
+

+ Bind to this address to listen for NATD connections. (Default: 127.0.0.1). +

+
+
+AutomapHostsOnResolve 0|1 +
+
+

+ When this option is enabled, and we get a request to resolve an address + that ends with one of the suffixes in AutomapHostsSuffixes, we map an + unused virtual address to that address, and return the new virtual address. + This is handy for making ".onion" addresses work with applications that + resolve an address and then connect to it. (Default: 0). +

+
+
+AutomapHostsSuffixes SUFFIX,SUFFIX,… +
+
+

+ A comma-separated list of suffixes to use with AutomapHostsOnResolve. + The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). +

+
+
+DNSPort PORT|auto +
+
+

+ If non-zero, Tor listens for UDP DNS requests on this port and resolves + them anonymously. Set it to "auto" to have Tor pick a port for + you. (Default: 0). +

+
+
+DNSListenAddress IP[:PORT] +
+
+

+ Bind to this address to listen for DNS connections. (Default: 127.0.0.1). +

+
+
+ClientDNSRejectInternalAddresses 0|1 +
+
+

+ If true, Tor does not believe any anonymously retrieved DNS answer that + tells it that an address resolves to an internal address (like 127.0.0.1 or + 192.168.0.1). This option prevents certain browser-based attacks; don’t + turn it off unless you know what you’re doing. (Default: 1). +

+
+
+ClientRejectInternalAddresses 0|1 +
+
+

+ If true, Tor does not try to fulfill requests to connect to an internal + address (like 127.0.0.1 or 192.168.0.1) unless a exit node is + specifically requested (for example, via a .exit hostname, or a + controller request). (Default: 1). +

+
+
+DownloadExtraInfo 0|1 +
+
+

+ If true, Tor downloads and caches "extra-info" documents. These documents + contain information about servers other than the information in their + regular router descriptors. Tor does not use this information for anything + itself; to save bandwidth, leave this option turned off. (Default: 0). +

+
+
+FallbackNetworkstatusFile FILENAME +
+
+

+ If Tor doesn’t have a cached networkstatus file, it starts out using this + one instead. Even if this file is out of date, Tor can still use it to + learn about directory mirrors, so it doesn’t need to put load on the + authorities. (Default: None). +

+
+
+WarnPlaintextPorts port,port,… +
+
+

+ Tells Tor to issue a warnings whenever the user tries to make an anonymous + connection to one of these ports. This option is designed to alert users + to services that risk sending passwords in the clear. (Default: + 23,109,110,143). +

+
+
+RejectPlaintextPorts port,port,… +
+
+

+ Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor + will instead refuse to make the connection. (Default: None). +

+
+
+AllowSingleHopCircuits 0|1 +
+
+

+ When this option is set, the attached Tor controller can use relays + that have the AllowSingleHopExits option turned on to build + one-hop Tor connections. (Default: 0) +

+
+
+
+

SERVER OPTIONS

+
+

The following options are useful only for servers (that is, if ORPort +is non-zero):

+
+
+Address address +
+
+

+ The IP address or fully qualified domain name of this server (e.g. + moria.mit.edu). You can leave this unset, and Tor will guess your IP + address. This IP address is the one used to tell clients and other + servers where to find your Tor server; it doesn’t affect the IP that your + Tor client binds to. To bind to a different address, use the + *ListenAddress and OutboundBindAddress options. +

+
+
+AllowSingleHopExits 0|1 +
+
+

+ This option controls whether clients can use this server as a single hop + proxy. If set to 1, clients can use this server as an exit even if it is + the only hop in the circuit. Note that most clients will refuse to use + servers that set this option, since most clients have + ExcludeSingleHopRelays set. (Default: 0) +

+
+
+AssumeReachable 0|1 +
+
+

+ This option is used when bootstrapping a new Tor network. If set to 1, + don’t do self-reachability testing; just upload your server descriptor + immediately. If AuthoritativeDirectory is also set, this option + instructs the dirserver to bypass remote reachability testing too and list + all connected servers as running. +

+
+
+BridgeRelay 0|1 +
+
+

+ Sets the relay to act as a "bridge" with respect to relaying connections + from bridge users to the Tor network. It mainly causes Tor to publish a + server descriptor to the bridge database, rather than publishing a relay + descriptor to the public directory authorities. +

+
+
+ContactInfo email_address +
+
+

+ Administrative contact information for server. This line might get picked + up by spam harvesters, so you may want to obscure the fact that it’s an + email address. +

+
+
+ExitPolicy policy,policy,… +
+
+

+ Set an exit policy for this server. Each policy is of the form + "accept|reject ADDR[/MASK][:PORT]". If /MASK is + omitted then this policy just applies to the host given. Instead of giving + a host or network you can also use "*" to denote the universe (0.0.0.0/0). + PORT can be a single port number, an interval of ports + "FROM_PORT-TO_PORT", or "*". If PORT is omitted, that means + "*".
+
+ For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*" would + reject any traffic destined for MIT except for web.mit.edu, and accept + anything else.
+
+ To specify all internal and link-local networks (including 0.0.0.0/8, + 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and + 172.16.0.0/12), you can use the "private" alias instead of an address. + These addresses are rejected by default (at the beginning of your exit + policy), along with your public IP address, unless you set the + ExitPolicyRejectPrivate config option to 0. For example, once you’ve done + that, you could allow HTTP to 127.0.0.1 and block all other connections to + internal networks with "accept 127.0.0.1:80,reject private:*", though that + may also allow connections to your own computer that are addressed to its + public (external) IP address. See RFC 1918 and RFC 3330 for more details + about internal and reserved IP address space.
+
+ This directive can be specified multiple times so you don’t have to put it + all on one line.
+
+ Policies are considered first to last, and the first match wins. If you + want to _replace_ the default exit policy, end your exit policy with + either a reject *:* or an accept *:*. Otherwise, you’re _augmenting_ + (prepending to) the default exit policy. The default exit policy is:
+

+
+
+
reject *:25
+reject *:119
+reject *:135-139
+reject *:445
+reject *:563
+reject *:1214
+reject *:4661-4666
+reject *:6346-6429
+reject *:6699
+reject *:6881-6999
+accept *:*
+
+
+
+ExitPolicyRejectPrivate 0|1 +
+
+

+ Reject all private (local) networks, along with your own public IP address, + at the beginning of your exit policy. See above entry on ExitPolicy. + (Default: 1) +

+
+
+MaxOnionsPending NUM +
+
+

+ If you have more than this number of onionskins queued for decrypt, reject + new ones. (Default: 100) +

+
+
+MyFamily node,node,… +
+
+

+ Declare that this Tor server is controlled or administered by a group or + organization identical or similar to that of the other servers, defined by + their identity fingerprints or nicknames. When two servers both declare + that they are in the same 'family', Tor clients will not use them in the + same circuit. (Each server only needs to list the other servers in its + family; it doesn’t need to list itself, but it won’t hurt.) +

+
+
+Nickname name +
+
+

+ Set the server’s nickname to 'name'. Nicknames must be between 1 and 19 + characters inclusive, and must contain only the characters [a-zA-Z0-9]. +

+
+
+NumCPUs num +
+
+

+ How many processes to use at once for decrypting onionskins. (Default: 1) +

+
+
+ORPort PORT|auto +
+
+

+ Advertise this port to listen for connections from Tor clients and + servers. This option is required to be a Tor server. + Set it to "auto" to have Tor pick a port for you. (Default: 0). +

+
+
+ORListenAddress IP[:PORT] +
+
+

+ Bind to this IP address to listen for connections from Tor clients and + servers. If you specify a port, bind to this port rather than the one + specified in ORPort. (Default: 0.0.0.0) This directive can be specified + multiple times to bind to multiple addresses/ports. +

+
+
+PublishServerDescriptor 0|1|v1|v2|v3|bridge,… +
+
+

+ This option specifies which descriptors Tor will publish when acting as + a relay. You can + choose multiple arguments, separated by commas. +
+ If this option is set to 0, Tor will not publish its + descriptors to any directories. (This is useful if you’re testing + out your server, or if you’re using a Tor controller that handles directory + publishing for you.) Otherwise, Tor will publish its descriptors of all + type(s) specified. The default is "1", + which means "if running as a server, publish the + appropriate descriptors to the authorities". +

+
+
+ShutdownWaitLength NUM +
+
+

+ When we get a SIGINT and we’re a server, we begin shutting down: + we close listeners and start refusing new circuits. After NUM + seconds, we exit. If we get a second SIGINT, we exit immedi- + ately. (Default: 30 seconds) +

+
+
+AccountingMax N bytes|KB|MB|GB|TB +
+
+

+ Never send more than the specified number of bytes in a given accounting + period, or receive more than that number in the period. For example, with + AccountingMax set to 1 GB, a server could send 900 MB and receive 800 MB + and continue running. It will only hibernate once one of the two reaches 1 + GB. When the number of bytes gets low, Tor will stop accepting new + connections and circuits. When the number of bytes + is exhausted, Tor will hibernate until some + time in the next accounting period. To prevent all servers from waking at + the same time, Tor will also wait until a random point in each period + before waking up. If you have bandwidth cost issues, enabling hibernation + is preferable to setting a low bandwidth, since it provides users with a + collection of fast servers that are up some of the time, which is more + useful than a set of slow servers that are always "available". +

+
+
+AccountingStart day|week|month [day] HH:MM +
+
+

+ Specify how long accounting periods last. If month is given, each + accounting period runs from the time HH:MM on the dayth day of one + month to the same day and time of the next. (The day must be between 1 and + 28.) If week is given, each accounting period runs from the time HH:MM + of the dayth day of one week to the same day and time of the next week, + with Monday as day 1 and Sunday as day 7. If day is given, each + accounting period runs from the time HH:MM each day to the same time on + the next day. All times are local, and given in 24-hour time. (Defaults to + "month 1 0:00".) +

+
+
+RefuseUnknownExits 0|1|auto +
+
+

+ Prevent nodes that don’t appear in the consensus from exiting using this + relay. If the option is 1, we always block exit attempts from such + nodes; if it’s 0, we never do, and if the option is "auto", then we do + whatever the authorities suggest in the consensus. (Defaults to auto.) +

+
+
+ServerDNSResolvConfFile filename +
+
+

+ Overrides the default DNS configuration with the configuration in + filename. The file format is the same as the standard Unix + "resolv.conf" file (7). This option, like all other ServerDNS options, + only affects name lookups that your server does on behalf of clients. + (Defaults to use the system DNS configuration.) +

+
+
+ServerDNSAllowBrokenConfig 0|1 +
+
+

+ If this option is false, Tor exits immediately if there are problems + parsing the system DNS configuration or connecting to nameservers. + Otherwise, Tor continues to periodically retry the system nameservers until + it eventually succeeds. (Defaults to "1".) +

+
+
+ServerDNSSearchDomains 0|1 +
+
+

+ If set to 1, then we will search for addresses in the local search domain. + For example, if this system is configured to believe it is in + "example.com", and a client tries to connect to "www", the client will be + connected to "www.example.com". This option only affects name lookups that + your server does on behalf of clients. (Defaults to "0".) +

+
+
+ServerDNSDetectHijacking 0|1 +
+
+

+ When this option is set to 1, we will test periodically to determine + whether our local nameservers have been configured to hijack failing DNS + requests (usually to an advertising site). If they are, we will attempt to + correct this. This option only affects name lookups that your server does + on behalf of clients. (Defaults to "1".) +

+
+
+ServerDNSTestAddresses address,address,… +
+
+

+ When we’re detecting DNS hijacking, make sure that these valid addresses + aren’t getting redirected. If they are, then our DNS is completely useless, + and we’ll reset our exit policy to "reject :". This option only affects + name lookups that your server does on behalf of clients. (Defaults to + "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org".) +

+
+
+ServerDNSAllowNonRFC953Hostnames 0|1 +
+
+

+ When this option is disabled, Tor does not try to resolve hostnames + containing illegal characters (like @ and :) rather than sending them to an + exit node to be resolved. This helps trap accidental attempts to resolve + URLs and so on. This option only affects name lookups that your server does + on behalf of clients. (Default: 0) +

+
+
+BridgeRecordUsageByCountry 0|1 +
+
+

+ When this option is enabled and BridgeRelay is also enabled, and we have + GeoIP data, Tor keeps a keep a per-country count of how many client + addresses have contacted it so that it can help the bridge authority guess + which countries have blocked access to it. (Default: 1) +

+
+
+ServerDNSRandomizeCase 0|1 +
+
+

+ When this option is set, Tor sets the case of each character randomly in + outgoing DNS requests, and makes sure that the case matches in DNS replies. + This so-called "0x20 hack" helps resist some types of DNS poisoning attack. + For more information, see "Increased DNS Forgery Resistance through + 0x20-Bit Encoding". This option only affects name lookups that your server + does on behalf of clients. (Default: 1) +

+
+
+GeoIPFile filename +
+
+

+ A filename containing GeoIP data, for use with BridgeRecordUsageByCountry. +

+
+
+CellStatistics 0|1 +
+
+

+ When this option is enabled, Tor writes statistics on the mean time that + cells spend in circuit queues to disk every 24 hours. (Default: 0) +

+
+
+DirReqStatistics 0|1 +
+
+

+ When this option is enabled, Tor writes statistics on the number and + response time of network status requests to disk every 24 hours. + (Default: 0) +

+
+
+EntryStatistics 0|1 +
+
+

+ When this option is enabled, Tor writes statistics on the number of + directly connecting clients to disk every 24 hours. (Default: 0) +

+
+
+ExitPortStatistics 0|1 +
+
+

+ When this option is enabled, Tor writes statistics on the number of relayed + bytes and opened stream per exit port to disk every 24 hours. (Default: 0) +

+
+
+ExtraInfoStatistics 0|1 +
+
+

+ When this option is enabled, Tor includes previously gathered statistics in + its extra-info documents that it uploads to the directory authorities. + (Default: 0) +

+
+
+
+

DIRECTORY SERVER OPTIONS

+
+

The following options are useful only for directory servers (that is, +if DirPort is non-zero):

+
+
+AuthoritativeDirectory 0|1 +
+
+

+ When this option is set to 1, Tor operates as an authoritative directory + server. Instead of caching the directory, it generates its own list of + good servers, signs it, and sends that to the clients. Unless the clients + already have you listed as a trusted directory, you probably do not want + to set this option. Please coordinate with the other admins at + tor-ops@torproject.org if you think you should be a directory. +

+
+
+DirPortFrontPage FILENAME +
+
+

+ When this option is set, it takes an HTML file and publishes it as "/" on + the DirPort. Now relay operators can provide a disclaimer without needing + to set up a separate webserver. There’s a sample disclaimer in + contrib/tor-exit-notice.html. +

+
+
+V1AuthoritativeDirectory 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor + generates version 1 directory and running-routers documents (for legacy + Tor clients up to 0.1.0.x). +

+
+
+V2AuthoritativeDirectory 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor + generates version 2 network statuses and serves descriptors, etc as + described in doc/spec/dir-spec-v2.txt (for Tor clients and servers running + 0.1.1.x and 0.1.2.x). +

+
+
+V3AuthoritativeDirectory 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor + generates version 3 network statuses and serves descriptors, etc as + described in doc/spec/dir-spec.txt (for Tor clients and servers running at + least 0.2.0.x). +

+
+
+VersioningAuthoritativeDirectory 0|1 +
+
+

+ When this option is set to 1, Tor adds information on which versions of + Tor are still believed safe for use to the published directory. Each + version 1 authority is automatically a versioning authority; version 2 + authorities provide this service optionally. See RecommendedVersions, + RecommendedClientVersions, and RecommendedServerVersions. +

+
+
+NamingAuthoritativeDirectory 0|1 +
+
+

+ When this option is set to 1, then the server advertises that it has + opinions about nickname-to-fingerprint bindings. It will include these + opinions in its published network-status pages, by listing servers with + the flag "Named" if a correct binding between that nickname and fingerprint + has been registered with the dirserver. Naming dirservers will refuse to + accept or publish descriptors that contradict a registered binding. See + approved-routers in the FILES section below. +

+
+
+HSAuthoritativeDir 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor also + accepts and serves v0 hidden service descriptors, + which are produced and used by Tor 0.2.1.x and older. (Default: 0) +

+
+
+HidServDirectoryV2 0|1 +
+
+

+ When this option is set, Tor accepts and serves v2 hidden service + descriptors. Setting DirPort is not required for this, because clients + connect via the ORPort by default. (Default: 1) +

+
+
+BridgeAuthoritativeDir 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor + accepts and serves router descriptors, but it caches and serves the main + networkstatus documents rather than generating its own. (Default: 0) +

+
+
+MinUptimeHidServDirectoryV2 N seconds|minutes|hours|days|weeks +
+
+

+ Minimum uptime of a v2 hidden service directory to be accepted as such by + authoritative directories. (Default: 25 hours) +

+
+
+DirPort PORT|auto +
+
+

+ If this option is nonzero, advertise the directory service on this port. + Set it to "auto" to have Tor pick a port for you. (Default: 0) +

+
+
+DirListenAddress IP[:PORT] +
+
+

+ Bind the directory service to this address. If you specify a port, bind to + this port rather than the one specified in DirPort. (Default: 0.0.0.0) + This directive can be specified multiple times to bind to multiple + addresses/ports. +

+
+
+DirPolicy policy,policy,… +
+
+

+ Set an entrance policy for this server, to limit who can connect to the + directory ports. The policies have the same form as exit policies above. +

+
+
+FetchV2Networkstatus 0|1 +
+
+

+ If set, we try to fetch the (obsolete, unused) version 2 network status + consensus documents from the directory authorities. No currently + supported Tor version uses them. (Default: 0.) +

+
+
+
+

DIRECTORY AUTHORITY SERVER OPTIONS

+
+
+
+RecommendedVersions STRING +
+
+

+ STRING is a comma-separated list of Tor versions currently believed to be + safe. The list is included in each directory, and nodes which pull down the + directory learn whether they need to upgrade. This option can appear + multiple times: the values from multiple lines are spliced together. When + this is set then VersioningAuthoritativeDirectory should be set too. +

+
+
+RecommendedClientVersions STRING +
+
+

+ STRING is a comma-separated list of Tor versions currently believed to be + safe for clients to use. This information is included in version 2 + directories. If this is not set then the value of RecommendedVersions + is used. When this is set then VersioningAuthoritativeDirectory should + be set too. +

+
+
+RecommendedServerVersions STRING +
+
+

+ STRING is a comma-separated list of Tor versions currently believed to be + safe for servers to use. This information is included in version 2 + directories. If this is not set then the value of RecommendedVersions + is used. When this is set then VersioningAuthoritativeDirectory should + be set too. +

+
+
+ConsensusParams STRING +
+
+

+ STRING is a space-separated list of key=value pairs that Tor will include + in the "params" line of its networkstatus vote. +

+
+
+DirAllowPrivateAddresses 0|1 +
+
+

+ If set to 1, Tor will accept router descriptors with arbitrary "Address" + elements. Otherwise, if the address is not an IP address or is a private IP + address, it will reject the router descriptor. Defaults to 0. +

+
+
+AuthDirBadDir AddressPattern… +
+
+

+ Authoritative directories only. A set of address patterns for servers that + will be listed as bad directories in any network status document this + authority publishes, if AuthDirListBadDirs is set. +

+
+
+AuthDirBadExit AddressPattern… +
+
+

+ Authoritative directories only. A set of address patterns for servers that + will be listed as bad exits in any network status document this authority + publishes, if AuthDirListBadExits is set. +

+
+
+AuthDirInvalid AddressPattern… +
+
+

+ Authoritative directories only. A set of address patterns for servers that + will never be listed as "valid" in any network status document that this + authority publishes. +

+
+
+AuthDirReject AddressPattern… +
+
+

+ Authoritative directories only. A set of address patterns for servers that + will never be listed at all in any network status document that this + authority publishes, or accepted as an OR address in any descriptor + submitted for publication by this authority. +

+
+
+AuthDirListBadDirs 0|1 +
+
+

+ Authoritative directories only. If set to 1, this directory has some + opinion about which nodes are unsuitable as directory caches. (Do not set + this to 1 unless you plan to list non-functioning directories as bad; + otherwise, you are effectively voting in favor of every declared + directory.) +

+
+
+AuthDirListBadExits 0|1 +
+
+

+ Authoritative directories only. If set to 1, this directory has some + opinion about which nodes are unsuitable as exit nodes. (Do not set this to + 1 unless you plan to list non-functioning exits as bad; otherwise, you are + effectively voting in favor of every declared exit as an exit.) +

+
+
+AuthDirRejectUnlisted 0|1 +
+
+

+ Authoritative directories only. If set to 1, the directory server rejects + all uploaded server descriptors that aren’t explicitly listed in the + fingerprints file. This acts as a "panic button" if we get hit with a Sybil + attack. (Default: 0) +

+
+
+AuthDirMaxServersPerAddr NUM +
+
+

+ Authoritative directories only. The maximum number of servers that we will + list as acceptable on a single IP address. Set this to "0" for "no limit". + (Default: 2) +

+
+
+AuthDirMaxServersPerAuthAddr NUM +
+
+

+ Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies + to addresses shared with directory authorities. (Default: 5) +

+
+
+AuthDirFastGuarantee N bytes|KB|MB|GB +
+
+

+ Authoritative directories only. If non-zero, always vote the + Fast flag for any relay advertising this amount of capacity or + more. (Default: 20 KB) +

+
+
+AuthDirGuardBWGuarantee N bytes|KB|MB|GB +
+
+

+ Authoritative directories only. If non-zero, this advertised capacity + or more is always sufficient to satisfy the bandwidth requirement + for the Guard flag. (Default: 250 KB) +

+
+
+BridgePassword Password +
+
+

+ If set, contains an HTTP authenticator that tells a bridge authority to + serve all requested bridge information. Used for debugging. (Default: + not set.) +

+
+
+V3AuthVotingInterval N minutes|hours +
+
+

+ V3 authoritative directories only. Configures the server’s preferred voting + interval. Note that voting will actually happen at an interval chosen + by consensus from all the authorities' preferred intervals. This time + SHOULD divide evenly into a day. (Default: 1 hour) +

+
+
+V3AuthVoteDelay N minutes|hours +
+
+

+ V3 authoritative directories only. Configures the server’s preferred delay + between publishing its vote and assuming it has all the votes from all the + other authorities. Note that the actual time used is not the server’s + preferred time, but the consensus of all preferences. (Default: 5 minutes.) +

+
+
+V3AuthDistDelay N minutes|hours +
+
+

+ V3 authoritative directories only. Configures the server’s preferred delay + between publishing its consensus and signature and assuming it has all the + signatures from all the other authorities. Note that the actual time used + is not the server’s preferred time, but the consensus of all preferences. + (Default: 5 minutes.) +

+
+
+V3AuthNIntervalsValid NUM +
+
+

+ V3 authoritative directories only. Configures the number of VotingIntervals + for which each consensus should be valid for. Choosing high numbers + increases network partitioning risks; choosing low numbers increases + directory traffic. Note that the actual number of intervals used is not the + server’s preferred number, but the consensus of all preferences. Must be at + least 2. (Default: 3.) +

+
+
+V3BandwidthsFile FILENAME +
+
+

+ V3 authoritative directories only. Configures the location of the + bandiwdth-authority generated file storing information on relays' measured + bandwidth capacities. (Default: unset.) +

+
+
+V3AuthUseLegacyKey 0|1 +
+
+

+ If set, the directory authority will sign consensuses not only with its + own signing key, but also with a "legacy" key and certificate with a + different identity. This feature is used to migrate directory authority + keys in the event of a compromise. (Default: 0.) +

+
+
+RephistTrackTime N seconds|minutes|hours|days|weeks +
+
+

+ Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn’t + changed for a given amount of time. (Default: 24 hours) +

+
+
+VoteOnHidServDirectoriesV2 0|1 +
+
+

+ When this option is set in addition to AuthoritativeDirectory, Tor + votes on whether to accept relays as hidden service directories. + (Default: 1) +

+
+
+
+

HIDDEN SERVICE OPTIONS

+
+

The following options are used to configure a hidden service.

+
+
+HiddenServiceDir DIRECTORY +
+
+

+ Store data files for a hidden service in DIRECTORY. Every hidden service + must have a separate directory. You may use this option multiple times to + specify multiple services. DIRECTORY must be an existing directory. +

+
+
+HiddenServicePort VIRTPORT [TARGET] +
+
+

+ Configure a virtual port VIRTPORT for a hidden service. You may use this + option multiple times; each time applies to the service using the most + recent hiddenservicedir. By default, this option maps the virtual port to + the same port on 127.0.0.1. You may override the target port, address, or + both by specifying a target of addr, port, or addr:port. You may also have + multiple lines with the same VIRTPORT: when a user connects to that + VIRTPORT, one of the TARGETs from those lines will be chosen at random. +

+
+
+PublishHidServDescriptors 0|1 +
+
+

+ If set to 0, Tor will run any hidden services you configure, but it won’t + advertise them to the rendezvous directory. This option is only useful if + you’re using a Tor controller that handles hidserv publishing for you. + (Default: 1) +

+
+
+HiddenServiceVersion version,version,… +
+
+

+ A list of rendezvous service descriptor versions to publish for the hidden + service. Currently, only version 2 is supported. (Default: 2) +

+
+
+HiddenServiceAuthorizeClient auth-type client-name,client-name,… +
+
+

+ If configured, the hidden service is accessible for authorized clients + only. The auth-type can either be 'basic' for a general-purpose + authorization protocol or 'stealth' for a less scalable protocol that also + hides service activity from unauthorized clients. Only clients that are + listed here are authorized to access the hidden service. Valid client names + are 1 to 19 characters long and only use characters in A-Za-z0-9+-_ (no + spaces). If this option is set, the hidden service is not accessible for + clients without authorization any more. Generated authorization data can be + found in the hostname file. Clients need to put this authorization data in + their configuration file using HidServAuth. +

+
+
+RendPostPeriod N seconds|minutes|hours|days|weeks +
+
+

+ Every time the specified period elapses, Tor uploads any rendezvous + service descriptors to the directory servers. This information is also + uploaded whenever it changes. (Default: 1 hour) +

+
+
+
+

TESTING NETWORK OPTIONS

+
+

The following options are used for running a testing Tor network.

+
+
+TestingTorNetwork 0|1 +
+
+

+ If set to 1, Tor adjusts default values of the configuration options below, + so that it is easier to set up a testing Tor network. May only be set if + non-default set of DirServers is set. Cannot be unset while Tor is running. + (Default: 0)
+

+
+
+
ServerDNSAllowBrokenConfig 1
+DirAllowPrivateAddresses 1
+EnforceDistinctSubnets 0
+AssumeReachable 1
+AuthDirMaxServersPerAddr 0
+AuthDirMaxServersPerAuthAddr 0
+ClientDNSRejectInternalAddresses 0
+ClientRejectInternalAddresses 0
+ExitPolicyRejectPrivate 0
+V3AuthVotingInterval 5 minutes
+V3AuthVoteDelay 20 seconds
+V3AuthDistDelay 20 seconds
+MinUptimeHidServDirectoryV2 0 seconds
+TestingV3AuthInitialVotingInterval 5 minutes
+TestingV3AuthInitialVoteDelay 20 seconds
+TestingV3AuthInitialDistDelay 20 seconds
+TestingAuthDirTimeToLearnReachability 0 minutes
+TestingEstimatedDescriptorPropagationTime 0 minutes
+
+
+
+TestingV3AuthInitialVotingInterval N minutes|hours +
+
+

+ Like V3AuthVotingInterval, but for initial voting interval before the first + consensus has been created. Changing this requires that + TestingTorNetwork is set. (Default: 30 minutes) +

+
+
+TestingV3AuthInitialVoteDelay N minutes|hours +
+
+

+ Like TestingV3AuthInitialVoteDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + TestingTorNetwork is set. (Default: 5 minutes) +

+
+
+TestingV3AuthInitialDistDelay N minutes|hours +
+
+

+ Like TestingV3AuthInitialDistDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + TestingTorNetwork is set. (Default: 5 minutes) +

+
+
+TestingAuthDirTimeToLearnReachability N minutes|hours +
+
+

+ After starting as an authority, do not make claims about whether routers + are Running until this much time has passed. Changing this requires + that TestingTorNetwork is set. (Default: 30 minutes) +

+
+
+TestingEstimatedDescriptorPropagationTime N minutes|hours +
+
+

+ Clients try downloading router descriptors from directory caches after this + time. Changing this requires that TestingTorNetwork is set. (Default: + 10 minutes) +

+
+
+
+

SIGNALS

+
+

Tor catches the following signals:

+
+
+SIGTERM +
+
+

+ Tor will catch this, clean up and sync to disk if necessary, and exit. +

+
+
+SIGINT +
+
+

+ Tor clients behave as with SIGTERM; but Tor servers will do a controlled + slow shutdown, closing listeners and waiting 30 seconds before exiting. + (The delay can be configured with the ShutdownWaitLength config option.) +

+
+
+SIGHUP +
+
+

+ The signal instructs Tor to reload its configuration (including closing and + reopening logs), and kill and restart its helper processes if applicable. +

+
+
+SIGUSR1 +
+
+

+ Log statistics about current connections, past connections, and throughput. +

+
+
+SIGUSR2 +
+
+

+ Switch all logs to loglevel debug. You can go back to the old loglevels by + sending a SIGHUP. +

+
+
+SIGCHLD +
+
+

+ Tor receives this signal when one of its helper processes has exited, so it + can clean up. +

+
+
+SIGPIPE +
+
+

+ Tor catches this signal and ignores it. +

+
+
+SIGXFSZ +
+
+

+ If this signal exists on your platform, Tor catches and ignores it. +

+
+
+
+

FILES

+
+
+
+/etc/tor/torrc +
+
+

+ The configuration file, which contains "option value" pairs. +

+
+
+/var/lib/tor/ +
+
+

+ The tor process stores keys and other data here. +

+
+
+DataDirectory/cached-status/ +
+
+

+ The most recently downloaded network status document for each authority. + Each file holds one such document; the filenames are the hexadecimal + identity key fingerprints of the directory authorities. +

+
+
+DataDirectory/cached-descriptors and cached-descriptors.new +
+
+

+ These files hold downloaded router statuses. Some routers may appear more + than once; if so, the most recently published descriptor is used. Lines + beginning with @-signs are annotations that contain more information about + a given router. The ".new" file is an append-only journal; when it gets + too large, all entries are merged into a new cached-descriptors file. +

+
+
+DataDirectory/cached-routers and cached-routers.new +
+
+

+ Obsolete versions of cached-descriptors and cached-descriptors.new. When + Tor can’t find the newer files, it looks here instead. +

+
+
+DataDirectory/state +
+
+

+ A set of persistent key-value mappings. These are documented in + the file. These include: +

+
    +
  • +

    +The current entry guards and their status. +

    +
    • +
  • +

    +The current bandwidth accounting values (unused so far; see + below). +

    +
    • +
  • +

    +When the file was last written +

    +
    • +
  • +

    +What version of Tor generated the state file +

    +
    • +
  • +

    +A short history of bandwidth usage, as produced in the router + descriptors. +

    +
    • +
+
+
+DataDirectory/bw_accounting +
+
+

+ Used to track bandwidth accounting values (when the current period starts + and ends; how much has been read and written so far this period). This file + is obsolete, and the data is now stored in the 'state' file as well. Only + used when bandwidth accounting is enabled. +

+
+
+DataDirectory/control_auth_cookie +
+
+

+ Used for cookie authentication with the controller. Location can be + overridden by the CookieAuthFile config option. Regenerated on startup. See + control-spec.txt for details. Only used when cookie authentication is + enabled. +

+
+
+DataDirectory/keys/* +
+
+

+ Only used by servers. Holds identity keys and onion keys. +

+
+
+DataDirectory/fingerprint +
+
+

+ Only used by servers. Holds the fingerprint of the server’s identity key. +

+
+
+DataDirectory/approved-routers +
+
+

+ Only for naming authoritative directory servers (see + NamingAuthoritativeDirectory). This file lists nickname to identity + bindings. Each line lists a nickname and a fingerprint separated by + whitespace. See your fingerprint file in the DataDirectory for an + example line. If the nickname is !reject then descriptors from the + given identity (fingerprint) are rejected by this server. If it is + !invalid then descriptors are accepted but marked in the directory as + not valid, that is, not recommended. +

+
+
+DataDirectory/router-stability +
+
+

+ Only used by authoritative directory servers. Tracks measurements for + router mean-time-between-failures so that authorities have a good idea of + how to set their Stable flags. +

+
+
+HiddenServiceDirectory/hostname +
+
+

+ The <base32-encoded-fingerprint>.onion domain name for this hidden service. + If the hidden service is restricted to authorized clients only, this file + also contains authorization data for all clients. +

+
+
+HiddenServiceDirectory/private_key +
+
+

+ The private key for this hidden service. +

+
+
+HiddenServiceDirectory/client_keys +
+
+

+ Authorization data for a hidden service that is only accessible by + authorized clients. +

+
+
+
+

SEE ALSO

+
+

privoxy(1), tsocks(1), torify(1)

+

https://www.torproject.org/

+
+

BUGS

+
+

Plenty, probably. Tor is still in development. Please report them.

+
+

AUTHORS

+
+

Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu].

+
+ + + -- cgit v1.2.3