diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 8 | ||||
| -rwxr-xr-x | doc/asciidoc-helper.sh | 3 | ||||
| -rw-r--r-- | doc/spec/dir-spec.txt | 12 | ||||
| -rw-r--r-- | doc/spec/proposals/000-index.txt | 2 | ||||
| -rw-r--r-- | doc/spec/proposals/175-automatic-node-promotion.txt | 238 | ||||
| -rw-r--r-- | doc/spec/tor-fw-helper-spec.txt | 57 | ||||
| -rw-r--r-- | doc/tor-fw-helper.1.txt | 68 | ||||
| -rw-r--r-- | doc/tor.1.txt | 21 |
8 files changed, 397 insertions, 12 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 68747c8d2d..500a57c7b6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,7 +14,11 @@ # just use the .1 and .html files. if USE_ASCIIDOC +if USE_FW_HELPER +asciidoc_files = tor tor-gencert tor-resolve torify tor-fw-helper +else asciidoc_files = tor tor-gencert tor-resolve torify +endif html_in = $(asciidoc_files:=.html.in) man_in = $(asciidoc_files:=.1.in) txt_in = $(asciidoc_files:=.1.txt) @@ -51,6 +55,7 @@ tor.html.in : tor.1.txt torify.html.in : torify.1.txt tor-gencert.html.in : tor-gencert.1.txt tor-resolve.html.in : tor-resolve.1.txt +tor-fw-helper.html.in : tor-fw-helper.1.txt # Generate the manpage from asciidoc, but don't do # machine-specific replacements yet @@ -61,6 +66,7 @@ tor.1.in : tor.1.txt torify.1.in : torify.1.txt tor-gencert.1.in : tor-gencert.1.txt tor-resolve.1.in : tor-resolve.1.txt +tor-fw-helper.1.in : tor-fw-helper.1.txt # use ../config.status to swap all machine-specific magic strings # in the asciidoc with their replacements. @@ -74,10 +80,12 @@ tor.1 : tor.1.in torify.1 : torify.1.in tor-gencert.1 : tor-gencert.1.in tor-resolve.1 : tor-resolve.1.in +tor-fw-helper.1 : tor-fw-helper.1.in tor.html : tor.html.in torify.html : torify.html.in tor-gencert.html : tor-gencert.html.in tor-resolve.html : tor-resolve.html.in +tor-fw-helper.html : tor-fw-helper.html.in CLEANFILES = $(asciidoc_product) config.log DISTCLEANFILES = $(html_in) $(man_in) diff --git a/doc/asciidoc-helper.sh b/doc/asciidoc-helper.sh index 00f8b8d07f..33e1360a71 100755 --- a/doc/asciidoc-helper.sh +++ b/doc/asciidoc-helper.sh @@ -17,6 +17,7 @@ output=$3 if [ "$1" = "html" ]; then input=${output%%.html.in}.1.txt base=${output%%.html.in} + if [ "$2" != none ]; then "$2" -d manpage -o $output $input; else @@ -32,7 +33,7 @@ if [ "$1" = "html" ]; then elif [ "$1" = "man" ]; then input=${output%%.1.in}.1.txt base=${output%%.1.in} - + if test "$2" = none; then echo "=================================="; echo; diff --git a/doc/spec/dir-spec.txt b/doc/spec/dir-spec.txt index 6e35deb00e..4a7a557b31 100644 --- a/doc/spec/dir-spec.txt +++ b/doc/spec/dir-spec.txt @@ -530,16 +530,8 @@ dns logic. Versions of Tor with this field set to false SHOULD NOT be used for reverse hostname lookups. - [All versions of Tor before 0.1.2.2-alpha should be assumed to have - this option set to 0 if it is not present. All Tor versions at - 0.1.2.2-alpha or later should be assumed to have this option set to - 1 if it is not present. Until 0.1.2.1-alpha-dev, this option was - not generated, even when the new DNS code was in use. Versions of Tor - before 0.1.2.1-alpha-dev did not parse this option, so it should be - marked "opt". The dnsworker logic has been removed, so this option - should not be used by new server code. However, it can still be - used, and should still be recognized by new code until Tor 0.1.2.x - is obsolete.] + [This option is obsolete. All Tor current servers should be presumed + to have the evdns backend.] "caches-extra-info" NL diff --git a/doc/spec/proposals/000-index.txt b/doc/spec/proposals/000-index.txt index f6f313e58d..8ea73540a3 100644 --- a/doc/spec/proposals/000-index.txt +++ b/doc/spec/proposals/000-index.txt @@ -94,6 +94,7 @@ Proposals by number: 172 GETINFO controller option for circuit information [ACCEPTED] 173 GETINFO Option Expansion [ACCEPTED] 174 Optimistic Data for Tor: Server Side [OPEN] +175 Automatically promoting Tor clients to nodes [DRAFT] Proposals by status: @@ -106,6 +107,7 @@ Proposals by status: 144 Increase the diversity of circuits by detecting nodes belonging the same provider 169 Eliminate TLS renegotiation for the Tor connection handshake [for 0.2.2] 170 Configuration options regarding circuit building + 175 Automatically promoting Tor clients to nodes [for ] NEEDS-REVISION: 131 Help users to verify they are using Tor OPEN: diff --git a/doc/spec/proposals/175-automatic-node-promotion.txt b/doc/spec/proposals/175-automatic-node-promotion.txt new file mode 100644 index 0000000000..c990b3f060 --- /dev/null +++ b/doc/spec/proposals/175-automatic-node-promotion.txt @@ -0,0 +1,238 @@ +Filename: 175-automatic-node-promotion.txt +Title: Automatically promoting Tor clients to nodes +Author: Steven Murdoch +Created: 12-Mar-2010 +Status: Draft + +1. Overview + + This proposal describes how Tor clients could determine when they + have sufficient bandwidth capacity and are sufficiently reliable to + become either bridges or Tor relays. When they meet this + criteria, they will automatically promote themselves, based on user + preferences. The proposal also defines the new controller messages + and options which will control this process. + + Note that for the moment, only transitions between client and + bridge are being considered. Transitions to public relay will + be considered at a future date, but will use the same + infrastructure for measuring capacity and reliability. + +2. Motivation and history + + Tor has a growing user-base and one of the major impediments to the + quality of service offered is the lack of network capacity. This is + particularly the case for bridges, because these are gradually + being blocked, and thus no longer of use to people within some + countries. By automatically promoting Tor clients to bridges, and + perhaps also to full public relays, this proposal aims to solve + these problems. + + Only Tor clients which are sufficiently useful should be promoted, + and the process of determining usefulness should be performed + without reporting the existence of the client to the central + authorities. The criteria used for determining usefulness will be + in terms of bandwidth capacity and uptime, but parameters should be + specified in the directory consensus. State stored at the client + should be in no more detail than necessary, to prevent sensitive + information being recorded. + +3. Design + +3.x Opt-in state model + + Tor can be in one of five node-promotion states: + + - off (O): Currently a client, and will stay as such + - auto (A): Currently a client, but will consider promotion + - bridge (B): Currently a bridge, and will stay as such + - auto-bridge (AB): Currently a bridge, but will consider promotion + - relay (R): Currently a public relay, and will stay as such + + The state can be fully controlled from the configuration file or + controller, but the normal state transitions are as follows: + + Any state -> off: User has opted out of node promotion + Off -> any state: Only permitted with user consent + + Auto -> auto-bridge: Tor has detected that it is sufficiently + reliable to be a *bridge* + Auto -> bridge: Tor has detected that it is sufficiently reliable + to be a *relay*, but the user has chosen to remain a *bridge* + Auto -> relay: Tor has detected that it is sufficiently reliable + to be *relay*, and will skip being a *bridge* + Auto-bridge -> relay: Tor has detected that it is sufficiently + reliable to be a *relay* + + Note that this model does not support automatic demotion. If this + is desirable, there should be some memory as to whether the + previous state was relay, bridge, or auto-bridge. Otherwise the + user may be prompted to become a relay, although he has opted to + only be a bridge. + +3.x User interaction policy + + There are a variety of options in how to involve the user into the + decision as to whether and when to perform node promotion. The + choice also may be different when Tor is running from Vidalia (and + thus can readily prompt the user for information), and standalone + (where Tor can only log messages, which may or may not be read). + + The option requiring minimal user interaction is to automatically + promote nodes according to reliability, and allow the user to opt + out, by changing settings in the configuration file or Vidalia user + interface. + + Alternatively, if a user interface is available, Tor could prompt + the user when it detects that a transition is available, and allow + the user to choose which of the available options to select. If + Vidalia is not available, it still may be possible to solicit an + email address on install, and contact the operator to ask whether + a transition to bridge or relay is permitted. + + Finally, Tor could by default not make any transition, and the user + would need to opt in by stating the maximum level (bridge or + relay) to which the node may automatically promote itself. + +3.x Performance monitoring model + + To prevent a large number of clients activating as relays, but + being too unreliable to be useful, clients should measure their + performance. If this performance meets a parameterized acceptance + criteria, a client should consider promotion. To measure + reliability, this proposal adopts a simple user model: + + - A user decides to use Tor at times which follow a Poisson + distribution + - At each time, the user will be happy if the bridge chosen has + adequate bandwidth and is reachable + - If the chosen bridge is down or slow too many times, the user + will consider Tor to be bad + + If we additionally assume that the recent history of relay + performance matches the current performance, we can measure + reliability by simulating this simple user. + + The following parameters are distributed to clients in the + directory consensus: + + - min_bandwidth: Minimum self-measured bandwidth for a node to be + considered useful, in bytes per second + - check_period: How long, in seconds, to wait between checking + reachability and bandwidth (on average) + - num_samples: Number of recent samples to keep + - num_useful: Minimum number of recent samples where the node was + reachable and had at least min_bandwidth capacity, for a client + to consider promoting to a bridge + + A different set of parameters may be used for considering when to + promote a bridge to a full relay, but this will be the subject of a + future revision of the proposal. + +3.x Performance monitoring algorithm + + The simulation described above can be implemented as follows: + + Every 60 seconds: + 1. Tor generates a random floating point number x in + the interval [0, 1). + 2. If x > (1 / (check_period / 60)) GOTO end; otherwise: + 3. Tor sets the value last_check to the current_time (in seconds) + 4. Tor measures reachability + 5. If the client is reachable, Tor measures its bandwidth + 6. If the client is reachable and the bandwidth is >= + min_bandwidth, the test has succeeded, otherwise it has failed. + 7. Tor adds the test result to the end of a ring-buffer containing + the last num_samples results: measurement_results + 8. Tor saves last_check and measurements_results to disk + 9. If the length of measurements_results == num_samples and + the number of successes >= num_useful, Tor should consider + promotion to a bridge + end. + + When Tor starts, it must fill in the samples for which it was not + running. This can only happen once the consensus has downloaded, + because the value of check_period is needed. + + 1. Tor generates a random number y from the Poisson distribution [1] + with lambda = (current_time - last_check) * (1 / check_period) + 2. Tor sets the value last_check to the current_time (in seconds) + 3. Add y test failures to the ring buffer measurements_results + 4. Tor saves last_check and measurements_results to disk + + In this way, a Tor client will measure its bandwidth and + reachability every check_period seconds, on average. Provided + check_period is sufficiently greater than a minute (say, at least an + hour), the times of check will follow a Poisson distribution. [2] + + While this does require that Tor does record the state of a client + over time, this does not leak much information. Only a binary + reachable/non-reachable is stored, and the timing of samples becomes + increasingly fuzzy as the data becomes less recent. + + On IP address changes, Tor should clear the ring-buffer, because + from the perspective of users with the old IP address, this node + might as well be a new one with no history. This policy may change + once we start allowing the bridge authority to hand out new IP + addresses given the fingerprint. + +3.x Bandwidth measurement + + Tor needs to measure its bandwidth to test the usefulness as a + bridge. A non-intrusive way to do this would be to passively measure + the peak data transfer rate since the last reachability test. Once + this exceeds min_bandwidth, Tor can set a flag that this node + currently has sufficient bandwidth to pass the bandwidth component + of the upcoming performance measurement. + + For the first version we may simply skip the bandwidth test, + because the existing reachability test sends 500 kB over several + circuits, and checks whether the node can transfer at least 50 + kB/s. This is probably good enough for a bridge, so this test + might be sufficient to record a success in the ring buffer. + +3.x New options + +3.x New controller message + +4. Migration plan + + We should start by setting a high bandwidth and uptime requirement + in the consensus, so as to avoid overloading the bridge authority + with too many bridges. Once we are confident our systems can scale, + the criteria can be gradually shifted down to gain more bridges. + +5. Related proposals + +6. Open questions: + + - What user interaction policy should we take? + + - When (if ever) should we turn a relay into an exit relay? + + - What should the rate limits be for auto-promoted bridges/relays? + Should we prompt the user for this? + + - Perhaps the bridge authority should tell potential bridges + whether to enable themselves, by taking into account whether + their IP address is blocked + + - How do we explain the possible risks of running a bridge/relay + * Use of bandwidth/congestion + * Publication of IP address + * Blocking from IRC (even for non-exit relays) + + - What feedback should we give to bridge relays, to encourage then + e.g. number of recent users (what about reserve bridges)? + + - Can clients back-off from doing these tests (yes, we should do + this) + +[1] For algorithms to generate random numbers from the Poisson + distribution, see: http://en.wikipedia.org/wiki/Poisson_distribution#Generating_Poisson-distributed_random_variables +[2] "The sample size n should be equal to or larger than 20 and the + probability of a single success, p, should be smaller than or equal to + .05. If n >= 100, the approximation is excellent if np is also <= 10." + http://www.itl.nist.gov/div898/handbook/pmc/section3/pmc331.htm (e-Handbook of Statistical Methods) + +% vim: spell ai et: diff --git a/doc/spec/tor-fw-helper-spec.txt b/doc/spec/tor-fw-helper-spec.txt new file mode 100644 index 0000000000..0068b26556 --- /dev/null +++ b/doc/spec/tor-fw-helper-spec.txt @@ -0,0 +1,57 @@ + + Tor's (little) Firewall Helper specification + Jacob Appelbaum + +0. Preface + + This document describes issues faced by Tor users who are behind NAT devices + and wish to share their resources with the rest of the Tor network. It also + explains a possible solution for some NAT devices. + +1. Overview + + Tor users often wish to relay traffic for the Tor network and their upstream + firewall thwarts their attempted generosity. Automatic port forwarding + configuration for many consumer NAT devices is often available with two common + protocols NAT-PMP[0] and UPnP[1]. + +2. Implementation + + tor-fw-helper is a program that implements basic port forwarding requests; it + may be used alone or called from Tor itself. + +2.1 Output format + + When tor-fw-helper has completed the requested action successfully, it will + report the following message to standard output: + + tor-fw-helper: SUCCESS + + If tor-fw-helper was unable to complete the requested action successfully, it + will report the following message to standard error: + + tor-fw-helper: FAILURE + + All informational messages are printed to standard output; all error messages + are printed to standard error. Messages other than SUCCESS and FAILURE + may be printed by any compliant tor-fw-helper. + +2.2 Output format stability + + The above SUCCESS and FAILURE messages are the only stable output formats + provided by this specification. tor-fw-helper-spec compliant implementations + must return SUCCESS or FAILURE as defined above. + +3. Security Concerns + + It is probably best to hand configure port forwarding and in the process, we + suggest disabling NAT-PMP and/or UPnP. This is of course absolutely confusing + to users and so we support automatic, non-authenticated NAT port mapping + protocols with compliant tor-fw-helper applications. + + NAT should not be considered a security boundary. NAT-PMP and UPnP are hacks + to deal with the shortcomings of user education about TCP/IP, IPv4 shortages, + and of course, NAT devices that suffer from horrible user interface design. + +[0] http://en.wikipedia.org/wiki/NAT_Port_Mapping_Protocol +[1] http://en.wikipedia.org/wiki/Universal_Plug_and_Play diff --git a/doc/tor-fw-helper.1.txt b/doc/tor-fw-helper.1.txt new file mode 100644 index 0000000000..49b0910380 --- /dev/null +++ b/doc/tor-fw-helper.1.txt @@ -0,0 +1,68 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html +tor-fw-helper(1) +================ +Jacob Appelbaum + +NAME +---- +tor-fw-helper - Manage upstream firewall/NAT devices + +SYNOPSIS +-------- +**tor-fw-helper** [-h|--help] [-T|--test] [-v|--verbose] [-g|--fetch-public-ip] + -i|--internal-or-port __TCP port__ [-e|--external-or-port _TCP port_] + [-d|--internal-dir-port _TCP port_] [-p|--external-dir-port _TCP port_] + +DESCRIPTION +----------- +**tor-fw-helper** currently supports Apple's NAT-PMP protocol and the UPnP +standard for TCP port mapping. It is written as the reference implementation of +tor-fw-helper-spec.txt and conforms to that loose plugin API. If your network +supports either NAT-PMP or UPnP, tor-fw-helper will attempt to automatically +map the required TCP ports for Tor's Or and Dir ports. + + +OPTIONS +------- +**-h** or **--help**:: + Display help text and exit. + +**-v**:: + Display verbose output. + +**-T** or **--test**:: + Display test information and print the test information in + tor-fw-helper.log + +**-g** or **--fetch-public-ip**:: + Fetch the the public ip address for each supported NAT helper method. + +**-i** or **--internal-or-port** __port__:: + Inform **tor-fw-helper** of your internal OR port. This is the only + required argument. + +**-e** or **--external-or-port** __port__:: + Inform **tor-fw-helper** of your external OR port. + +**-d** or **--internal-dir-port** __port__:: + Inform **tor-fw-helper** of your internal Dir port. + +**-p** or **--external-dir-port** __port__:: + Inform **tor-fw-helper** of your external Dir port. + +BUGS +---- +This probably doesn't run on Windows. That's not a big issue, since we don't +really want to deal with Windows before October 2010 anyway. + +SEE ALSO +-------- +**tor**(1) + + +See also the "tor-fw-helper-spec.txt" file, distributed with Tor. + +AUTHORS +------- + Jacob Appelbaum <jacob@torproject.org>, Steven J. Murdoch <Steven.Murdoch@cl.cam.ac.uk> diff --git a/doc/tor.1.txt b/doc/tor.1.txt index df2b17ed08..28f5a4288d 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -397,6 +397,11 @@ Other options can be specified either on the command-line (--option networkstatus. This is an advanced option; you generally shouldn't have to mess with it. (Default: not set.) +**DisableIOCP** **0**|**1**:: + If Tor was built to use the Libevent's "bufferevents" networking code + and you're running on Windows, setting this option to 1 will tell Libevent + not to use the Windows IOCP networking API. (Default: 1) + CLIENT OPTIONS -------------- @@ -855,7 +860,9 @@ is non-zero): 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) + How many processes to use at once for decrypting onionskins and other + parallelizable operations. If this is set to 0, Tor will try to detect + how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0) **ORPort** __PORT__:: Advertise this port to listen for connections from Tor clients and servers. @@ -866,6 +873,18 @@ is non-zero): specified in ORPort. (Default: 0.0.0.0) This directive can be specified multiple times to bind to multiple addresses/ports. +**PortForwarding** **0**|**1**:: + Attempt to automatically forward the DirPort and ORPort on a NAT router + connecting this Tor server to the Internet. If set, Tor will try both + NAT-PMP (common on Apple routers) and UPnP (common on routers from other + manufacturers). (Default: 0) + +**PortForwardingHelper** __filename__|__pathname__:: + If PortForwarding is set, use this executable to configure the forwarding. + If set to a filename, the system path will be searched for the executable. + If set to a path, only the specified path will be executed. + (Default: tor-fw-helper) + **PublishServerDescriptor** **0**|**1**|**v1**|**v2**|**v3**|**bridge**|**hidserv**,**...**:: This option specifies which descriptors Tor will publish when acting as a relay or hidden service. You can |