diff options
Diffstat (limited to 'doc/spec/proposals/135-private-tor-networks.txt')
| -rw-r--r-- | doc/spec/proposals/135-private-tor-networks.txt | 283 |
1 files changed, 0 insertions, 283 deletions
diff --git a/doc/spec/proposals/135-private-tor-networks.txt b/doc/spec/proposals/135-private-tor-networks.txt deleted file mode 100644 index 131bbb9068..0000000000 --- a/doc/spec/proposals/135-private-tor-networks.txt +++ /dev/null @@ -1,283 +0,0 @@ -Filename: 135-private-tor-networks.txt -Title: Simplify Configuration of Private Tor Networks -Version: $Revision$ -Last-Modified: $Date$ -Author: Karsten Loesing -Created: 29-Apr-2008 -Status: Closed -Target: 0.2.1.x -Implemented-In: 0.2.1.2-alpha - -Change history: - - 29-Apr-2008 Initial proposal for or-dev - 19-May-2008 Included changes based on comments by Nick to or-dev and - added a section for test cases. - 18-Jun-2008 Changed testing-network-only configuration option names. - -Overview: - - Configuring a private Tor network has become a time-consuming and - error-prone task with the introduction of the v3 directory protocol. In - addition to that, operators of private Tor networks need to set an - increasing number of non-trivial configuration options, and it is hard - to keep FAQ entries describing this task up-to-date. In this proposal we - (1) suggest to (optionally) accelerate timing of the v3 directory voting - process and (2) introduce an umbrella config option specifically aimed at - creating private Tor networks. - -Design: - - 1. Accelerate Timing of v3 Directory Voting Process - - Tor has reasonable defaults for setting up a large, Internet-scale - network with comparably high latencies and possibly wrong server clocks. - However, those defaults are bad when it comes to quickly setting up a - private Tor network for testing, either on a single node or LAN (things - might be different when creating a test network on PlanetLab or - something). Some time constraints should be made configurable for private - networks. The general idea is to accelerate everything that has to do - with propagation of directory information, but nothing else, so that a - private network is available as soon as possible. (As a possible - safeguard, changing these configuration values could be made dependent on - the umbrella configuration option introduced in 2.) - - 1.1. Initial Voting Schedule - - When a v3 directory does not know any consensus, it assumes an initial, - hard-coded VotingInterval of 30 minutes, VoteDelay of 5 minutes, and - DistDelay of 5 minutes. This is important for multiple, simultaneously - restarted directory authorities to meet at a common time and create an - initial consensus. Unfortunately, this means that it may take up to half - an hour (or even more) for a private Tor network to bootstrap. - - We propose to make these three time constants configurable (note that - V3AuthVotingInterval, V3AuthVoteDelay, and V3AuthDistDelay do not have an - effect on the _initial_ voting schedule, but only on the schedule that a - directory authority votes for). This can be achieved by introducing three - new configuration options: TestingV3AuthInitialVotingInterval, - TestingV3AuthInitialVoteDelay, and TestingV3AuthInitialDistDelay. - - As first safeguards, Tor should only accept configuration values for - TestingV3AuthInitialVotingInterval that divide evenly into the default - value of 30 minutes. The effect is that even if people misconfigured - their directory authorities, they would meet at the default values at the - latest. The second safeguard is to allow configuration only when the - umbrella configuration option TestingTorNetwork is set. - - 1.2. Immediately Provide Reachability Information (Running flag) - - The default behavior of a directory authority is to provide the Running - flag only after the authority is available for at least 30 minutes. The - rationale is that before that time, an authority simply cannot deliver - useful information about other running nodes. But for private Tor - networks this may be different. This is currently implemented in the code - as: - - /** If we've been around for less than this amount of time, our - * reachability information is not accurate. */ - #define DIRSERV_TIME_TO_GET_REACHABILITY_INFO (30*60) - - There should be another configuration option - TestingAuthDirTimeToLearnReachability with a default value of 30 minutes - that can be changed when running testing Tor networks, e.g. to 0 minutes. - The configuration value would simply replace the quoted constant. Again, - changing this option could be safeguarded by requiring the umbrella - configuration option TestingTorNetwork to be set. - - 1.3. Reduce Estimated Descriptor Propagation Time - - Tor currently assumes that it takes up to 10 minutes until router - descriptors are propagated from the authorities to directory caches. - This is not very useful for private Tor networks, and we want to be able - to reduce this time, so that clients can download router descriptors in a - timely manner. - - /** Clients don't download any descriptor this recent, since it will - * probably not have propagated to enough caches. */ - #define ESTIMATED_PROPAGATION_TIME (10*60) - - We suggest to introduce a new config option - TestingEstimatedDescriptorPropagationTime which defaults to 10 minutes, - but that can be set to any lower non-negative value, e.g. 0 minutes. The - same safeguards as in 1.2 could be used here, too. - - 2. Umbrella Option for Setting Up Private Tor Networks - - Setting up a private Tor network requires a number of specific settings - that are not required or useful when running Tor in the public Tor - network. Instead of writing down these options in a FAQ entry, there - should be a single configuration option, e.g. TestingTorNetwork, that - changes all required settings at once. Newer Tor versions would keep the - set of configuration options up-to-date. It should still remain possible - to manually overwrite the settings that the umbrella configuration option - affects. - - The following configuration options are set by TestingTorNetwork: - - - ServerDNSAllowBrokenResolvConf 1 - Ignore the situation that private relays are not aware of any name - servers. - - - DirAllowPrivateAddresses 1 - Allow router descriptors containing private IP addresses. - - - EnforceDistinctSubnets 0 - Permit building circuits with relays in the same subnet. - - - AssumeReachable 1 - Omit self-testing for reachability. - - - AuthDirMaxServersPerAddr 0 - - AuthDirMaxServersPerAuthAddr 0 - Permit an unlimited number of nodes on the same IP address. - - - ClientDNSRejectInternalAddresses 0 - Believe in DNS responses resolving to private IP addresses. - - - ExitPolicyRejectPrivate 0 - Allow exiting to private IP addresses. (This one is a matter of - taste---it might be dangerous to make this a default in a private - network, although people setting up private Tor networks should know - what they are doing.) - - - V3AuthVotingInterval 5 minutes - - V3AuthVoteDelay 20 seconds - - V3AuthDistDelay 20 seconds - Accelerate voting schedule after first consensus has been reached. - - - TestingV3AuthInitialVotingInterval 5 minutes - - TestingV3AuthInitialVoteDelay 20 seconds - - TestingV3AuthInitialDistDelay 20 seconds - Accelerate initial voting schedule until first consensus is reached. - - - TestingAuthDirTimeToLearnReachability 0 minutes - Consider routers as Running from the start of running an authority. - - - TestingEstimatedDescriptorPropagationTime 0 minutes - Clients try downloading router descriptors from directory caches, - even when they are not 10 minutes old. - - In addition to changing the defaults for these configuration options, - TestingTorNetwork can only be set when a user has manually configured - DirServer lines. - -Test: - - The implementation of this proposal must pass the following tests: - - 1. Set TestingTorNetwork and see if dependent configuration options are - correctly changed. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability - 250-TestingTorNetwork=1 - 250 TestingAuthDirTimeToLearnReachability=0 - QUIT - - 2. Set TestingTorNetwork and a dependent configuration value to see if - the provided value is used for the dependent option. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \ - TestingAuthDirTimeToLearnReachability 5 - telnet 127.0.0.1 9051 - AUTHENTICATE - GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability - 250-TestingTorNetwork=1 - 250 TestingAuthDirTimeToLearnReachability=5 - QUIT - - 3. Start with TestingTorNetwork set and change a dependent configuration - option later on. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - SETCONF TestingAuthDirTimeToLearnReachability=5 - GETCONF TestingAuthDirTimeToLearnReachability - 250 TestingAuthDirTimeToLearnReachability=5 - QUIT - - 4. Start with TestingTorNetwork set and a dependent configuration value, - and reset that dependent configuration value. The result should be - the testing-network specific default value. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \ - TestingAuthDirTimeToLearnReachability 5 - telnet 127.0.0.1 9051 - AUTHENTICATE - GETCONF TestingAuthDirTimeToLearnReachability - 250 TestingAuthDirTimeToLearnReachability=5 - RESETCONF TestingAuthDirTimeToLearnReachability - GETCONF TestingAuthDirTimeToLearnReachability - 250 TestingAuthDirTimeToLearnReachability=0 - QUIT - - 5. Leave TestingTorNetwork unset and check if dependent configuration - options are left unchanged. - - tor DataDirectory . ControlPort 9051 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability - 250-TestingTorNetwork=0 - 250 TestingAuthDirTimeToLearnReachability=1800 - QUIT - - 6. Leave TestingTorNetwork unset, but set dependent configuration option - which should fail. - - tor DataDirectory . ControlPort 9051 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \ - TestingAuthDirTimeToLearnReachability 0 - [warn] Failed to parse/validate config: - TestingAuthDirTimeToLearnReachability may only be changed in testing - Tor networks! - - 7. Start with TestingTorNetwork unset and change dependent configuration - option later on which should fail. - - tor DataDirectory . ControlPort 9051 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - SETCONF TestingAuthDirTimeToLearnReachability=0 - 513 Unacceptable option value: TestingAuthDirTimeToLearnReachability - may only be changed in testing Tor networks! - - 8. Start with TestingTorNetwork unset and set it later on which should - fail. - - tor DataDirectory . ControlPort 9051 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - SETCONF TestingTorNetwork=1 - 553 Transition not allowed: While Tor is running, changing - TestingTorNetwork is not allowed. - - 9. Start with TestingTorNetwork set and unset it later on which should - fail. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \ - "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" - telnet 127.0.0.1 9051 - AUTHENTICATE - RESETCONF TestingTorNetwork - 513 Unacceptable option value: TestingV3AuthInitialVotingInterval may - only be changed in testing Tor networks! - - 10. Set TestingTorNetwork, but do not provide an alternate DirServer - which should fail. - - tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 - [warn] Failed to parse/validate config: TestingTorNetwork may only be - configured in combination with a non-default set of DirServers. - |