mirror of
https://github.com/torproject/torspec.git
synced 2024-11-23 09:49:45 +00:00
6bd09d5076
Tor doesn't use SVN anymore, making $Revision$, $Id$ and $Date$ meaningless. Remove them without replacement.
282 lines
12 KiB
Plaintext
282 lines
12 KiB
Plaintext
Filename: 135-private-tor-networks.txt
|
|
Title: Simplify Configuration of Private Tor Networks
|
|
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.
|
|
|