proposals/135-private-tor-networks.txt

   1 Filename: 135-private-tor-networks.txt
   2 Title: Simplify Configuration of Private Tor Networks
   3 Author: Karsten Loesing
   4 Created: 29-Apr-2008
   5 Status: Closed
   6 Target: 0.2.1.x
   7 Implemented-In: 0.2.1.2-alpha
   8
   9 Change history:
  10
  11   29-Apr-2008  Initial proposal for or-dev
  12   19-May-2008  Included changes based on comments by Nick to or-dev and
  13                added a section for test cases.
  14   18-Jun-2008  Changed testing-network-only configuration option names.
  15
  16 Overview:
  17
  18   Configuring a private Tor network has become a time-consuming and
  19   error-prone task with the introduction of the v3 directory protocol. In
  20   addition to that, operators of private Tor networks need to set an
  21   increasing number of non-trivial configuration options, and it is hard
  22   to keep FAQ entries describing this task up-to-date. In this proposal we
  23   (1) suggest to (optionally) accelerate timing of the v3 directory voting
  24   process and (2) introduce an umbrella config option specifically aimed at
  25   creating private Tor networks.
  26
  27 Design:
  28
  29   1. Accelerate Timing of v3 Directory Voting Process
  30
  31   Tor has reasonable defaults for setting up a large, Internet-scale
  32   network with comparably high latencies and possibly wrong server clocks.
  33   However, those defaults are bad when it comes to quickly setting up a
  34   private Tor network for testing, either on a single node or LAN (things
  35   might be different when creating a test network on PlanetLab or
  36   something). Some time constraints should be made configurable for private
  37   networks. The general idea is to accelerate everything that has to do
  38   with propagation of directory information, but nothing else, so that a
  39   private network is available as soon as possible. (As a possible
  40   safeguard, changing these configuration values could be made dependent on
  41   the umbrella configuration option introduced in 2.)
  42
  43   1.1. Initial Voting Schedule
  44
  45   When a v3 directory does not know any consensus, it assumes an initial,
  46   hard-coded VotingInterval of 30 minutes, VoteDelay of 5 minutes, and
  47   DistDelay of 5 minutes. This is important for multiple, simultaneously
  48   restarted directory authorities to meet at a common time and create an
  49   initial consensus. Unfortunately, this means that it may take up to half
  50   an hour (or even more) for a private Tor network to bootstrap.
  51
  52   We propose to make these three time constants configurable (note that
  53   V3AuthVotingInterval, V3AuthVoteDelay, and V3AuthDistDelay do not have an
  54   effect on the _initial_ voting schedule, but only on the schedule that a
  55   directory authority votes for). This can be achieved by introducing three
  56   new configuration options: TestingV3AuthInitialVotingInterval,
  57   TestingV3AuthInitialVoteDelay, and TestingV3AuthInitialDistDelay.
  58
  59   As first safeguards, Tor should only accept configuration values for
  60   TestingV3AuthInitialVotingInterval that divide evenly into the default
  61   value of 30 minutes. The effect is that even if people misconfigured
  62   their directory authorities, they would meet at the default values at the
  63   latest. The second safeguard is to allow configuration only when the
  64   umbrella configuration option TestingTorNetwork is set.
  65
  66   1.2. Immediately Provide Reachability Information (Running flag)
  67
  68   The default behavior of a directory authority is to provide the Running
  69   flag only after the authority is available for at least 30 minutes. The
  70   rationale is that before that time, an authority simply cannot deliver
  71   useful information about other running nodes. But for private Tor
  72   networks this may be different. This is currently implemented in the code
  73   as:
  74
  75   /** If we've been around for less than this amount of time, our
  76    * reachability information is not accurate. */
  77   #define DIRSERV_TIME_TO_GET_REACHABILITY_INFO (30*60)
  78
  79   There should be another configuration option
  80   TestingAuthDirTimeToLearnReachability with a default value of 30 minutes
  81   that can be changed when running testing Tor networks, e.g. to 0 minutes.
  82   The configuration value would simply replace the quoted constant. Again,
  83   changing this option could be safeguarded by requiring the umbrella
  84   configuration option TestingTorNetwork to be set.
  85
  86   1.3. Reduce Estimated Descriptor Propagation Time
  87
  88   Tor currently assumes that it takes up to 10 minutes until router
  89   descriptors are propagated from the authorities to directory caches.
  90   This is not very useful for private Tor networks, and we want to be able
  91   to reduce this time, so that clients can download router descriptors in a
  92   timely manner.
  93
  94   /** Clients don't download any descriptor this recent, since it will
  95    * probably not have propagated to enough caches. */
  96   #define ESTIMATED_PROPAGATION_TIME (10*60)
  97
  98   We suggest to introduce a new config option
  99   TestingEstimatedDescriptorPropagationTime which defaults to 10 minutes,
 100   but that can be set to any lower non-negative value, e.g. 0 minutes. The
 101   same safeguards as in 1.2 could be used here, too.
 102
 103   2. Umbrella Option for Setting Up Private Tor Networks
 104
 105   Setting up a private Tor network requires a number of specific settings
 106   that are not required or useful when running Tor in the public Tor
 107   network. Instead of writing down these options in a FAQ entry, there
 108   should be a single configuration option, e.g. TestingTorNetwork, that
 109   changes all required settings at once. Newer Tor versions would keep the
 110   set of configuration options up-to-date. It should still remain possible
 111   to manually overwrite the settings that the umbrella configuration option
 112   affects.
 113
 114   The following configuration options are set by TestingTorNetwork:
 115
 116   - ServerDNSAllowBrokenResolvConf 1
 117       Ignore the situation that private relays are not aware of any name
 118       servers.
 119
 120   - DirAllowPrivateAddresses 1
 121       Allow router descriptors containing private IP addresses.
 122
 123   - EnforceDistinctSubnets 0
 124       Permit building circuits with relays in the same subnet.
 125
 126   - AssumeReachable 1
 127       Omit self-testing for reachability.
 128
 129   - AuthDirMaxServersPerAddr 0
 130   - AuthDirMaxServersPerAuthAddr 0
 131       Permit an unlimited number of nodes on the same IP address.
 132
 133   - ClientDNSRejectInternalAddresses 0
 134       Believe in DNS responses resolving to private IP addresses.
 135
 136   - ExitPolicyRejectPrivate 0
 137       Allow exiting to private IP addresses. (This one is a matter of
 138       taste---it might be dangerous to make this a default in a private
 139       network, although people setting up private Tor networks should know
 140       what they are doing.)
 141
 142   - V3AuthVotingInterval 5 minutes
 143   - V3AuthVoteDelay 20 seconds
 144   - V3AuthDistDelay 20 seconds
 145       Accelerate voting schedule after first consensus has been reached.
 146
 147   - TestingV3AuthInitialVotingInterval 5 minutes
 148   - TestingV3AuthInitialVoteDelay 20 seconds
 149   - TestingV3AuthInitialDistDelay 20 seconds
 150       Accelerate initial voting schedule until first consensus is reached.
 151
 152   - TestingAuthDirTimeToLearnReachability 0 minutes
 153       Consider routers as Running from the start of running an authority.
 154
 155   - TestingEstimatedDescriptorPropagationTime 0 minutes
 156       Clients try downloading router descriptors from directory caches,
 157       even when they are not 10 minutes old.
 158
 159   In addition to changing the defaults for these configuration options,
 160   TestingTorNetwork can only be set when a user has manually configured
 161   DirServer lines.
 162
 163 Test:
 164
 165   The implementation of this proposal must pass the following tests:
 166
 167   1. Set TestingTorNetwork and see if dependent configuration options are
 168      correctly changed.
 169
 170      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \
 171        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 172      telnet 127.0.0.1 9051
 173      AUTHENTICATE
 174      GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability
 175      250-TestingTorNetwork=1
 176      250 TestingAuthDirTimeToLearnReachability=0
 177      QUIT
 178
 179   2. Set TestingTorNetwork and a dependent configuration value to see if
 180      the provided value is used for the dependent option.
 181
 182      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \
 183        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \
 184        TestingAuthDirTimeToLearnReachability 5
 185      telnet 127.0.0.1 9051
 186      AUTHENTICATE
 187      GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability
 188      250-TestingTorNetwork=1
 189      250 TestingAuthDirTimeToLearnReachability=5
 190      QUIT
 191
 192   3. Start with TestingTorNetwork set and change a dependent configuration
 193      option later on.
 194
 195      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \
 196        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 197      telnet 127.0.0.1 9051
 198      AUTHENTICATE
 199      SETCONF TestingAuthDirTimeToLearnReachability=5
 200      GETCONF TestingAuthDirTimeToLearnReachability
 201      250 TestingAuthDirTimeToLearnReachability=5
 202      QUIT
 203
 204   4. Start with TestingTorNetwork set and a dependent configuration value,
 205      and reset that dependent configuration value. The result should be
 206      the testing-network specific default value.
 207
 208      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \
 209        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \
 210        TestingAuthDirTimeToLearnReachability 5
 211      telnet 127.0.0.1 9051
 212      AUTHENTICATE
 213      GETCONF TestingAuthDirTimeToLearnReachability
 214      250 TestingAuthDirTimeToLearnReachability=5
 215      RESETCONF TestingAuthDirTimeToLearnReachability
 216      GETCONF TestingAuthDirTimeToLearnReachability
 217      250 TestingAuthDirTimeToLearnReachability=0
 218      QUIT
 219
 220   5. Leave TestingTorNetwork unset and check if dependent configuration
 221      options are left unchanged.
 222
 223      tor DataDirectory . ControlPort 9051 DirServer \
 224        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 225      telnet 127.0.0.1 9051
 226      AUTHENTICATE
 227      GETCONF TestingTorNetwork TestingAuthDirTimeToLearnReachability
 228      250-TestingTorNetwork=0
 229      250 TestingAuthDirTimeToLearnReachability=1800
 230      QUIT
 231
 232   6. Leave TestingTorNetwork unset, but set dependent configuration option
 233      which should fail.
 234
 235      tor DataDirectory . ControlPort 9051 DirServer \
 236        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000" \
 237        TestingAuthDirTimeToLearnReachability 0
 238      [warn] Failed to parse/validate config:
 239      TestingAuthDirTimeToLearnReachability may only be changed in testing
 240      Tor networks!
 241
 242   7. Start with TestingTorNetwork unset and change dependent configuration
 243      option later on which should fail.
 244
 245      tor DataDirectory . ControlPort 9051 DirServer \
 246        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 247      telnet 127.0.0.1 9051
 248      AUTHENTICATE
 249      SETCONF TestingAuthDirTimeToLearnReachability=0
 250      513 Unacceptable option value: TestingAuthDirTimeToLearnReachability
 251      may only be changed in testing Tor networks!
 252
 253   8. Start with TestingTorNetwork unset and set it later on which should
 254      fail.
 255
 256      tor DataDirectory . ControlPort 9051 DirServer \
 257        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 258      telnet 127.0.0.1 9051
 259      AUTHENTICATE
 260      SETCONF TestingTorNetwork=1
 261      553 Transition not allowed: While Tor is running, changing
 262      TestingTorNetwork is not allowed.
 263
 264   9. Start with TestingTorNetwork set and unset it later on which should
 265      fail.
 266
 267      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1 DirServer \
 268        "mydir 127.0.0.1:1234 0000000000000000000000000000000000000000"
 269      telnet 127.0.0.1 9051
 270      AUTHENTICATE
 271      RESETCONF TestingTorNetwork
 272      513 Unacceptable option value: TestingV3AuthInitialVotingInterval may
 273      only be changed in testing Tor networks!
 274
 275  10. Set TestingTorNetwork, but do not provide an alternate DirServer
 276      which should fail.
 277
 278      tor DataDirectory . ControlPort 9051 TestingTorNetwork 1
 279      [warn] Failed to parse/validate config: TestingTorNetwork may only be
 280      configured in combination with a non-default set of DirServers.
 281