[or-cvs] r11163: Initial commit of a README about op-addon.py (torflow/trunk)
renner at seul.org
renner at seul.org
Sat Aug 18 12:41:30 UTC 2007
Author: renner
Date: 2007-08-18 08:41:30 -0400 (Sat, 18 Aug 2007)
New Revision: 11163
Added:
torflow/trunk/op-addon-README
Log:
Initial commit of a README about op-addon.py
Added: torflow/trunk/op-addon-README
===================================================================
--- torflow/trunk/op-addon-README (rev 0)
+++ torflow/trunk/op-addon-README 2007-08-18 12:41:30 UTC (rev 11163)
@@ -0,0 +1,227 @@
+* For instructions on how to get OP-Addon, go to section 8
+* Installation instructions and prerequisites can be found in section 9
+
+###############################################################################
+
+1. Introduction:
+
+ OP-Addon is intended for any people who are researching or experimenting with
+ circuit creation mechanisms and path selection in Tor, as well as for
+ ambitious Tor users, who want to optimize their performance in user-tasks or
+ otherwise customize the method of path selection at their own risk.
+
+ It is a controller for Tor (clients), written in Python, that can be applied
+ to any locally running onion proxy that has a control port configured. By
+ making use of the Tor control protocol, it replaces Tor's default path
+ selection and circuit management by highly configurable and customizable
+ mechanisms. The user can freely configure the desired method of path
+ selection, while the created paths can either be analyzed regarding their
+ performance, or used to handle user streams, e.g. for browsing the web.
+
+ The only performance test that is currently included, is a method of
+ measuring Tor latencies, that is based on violating the exit policy of the
+ last hop in a path. Using this method, it is possible to measure latencies
+ of complete n-hop circuits, as well as of single links between Tor routers
+ (see sections 5. & 6.).
+
+ If you do not know what this is all about, and plan to implement your own
+ application that creates circuits in a customized way or new measurings or
+ performance tests, please refer to section 7. The following sections will
+ explain the available features of OP-Addon that can be enabled and configured
+ using configuration options that are grouped in several sections
+ ('pathrc.example' contains a commented example configuration).
+
+2. General configurations (sections HOST_PORT and CIRC_MANAGEMENT):
+
+ In any case you will need to provide the host and port, where Tor is
+ listening for control connections (defaults are 127.0.0.1 and 9051). Control
+ port authentication will be added, as soon as I found a convenient way for
+ doing it. The option 'idle_circuits' lets the user specify a number of
+ circuits that shall be created preemptively and available at every time. This
+ can be set to any integer value between 0 and n. If you set it to 0, OP-Addon
+ will create a circuit, as soon as there is an incoming stream from any
+ application.
+
+3. Testing and user mode (section TESTING):
+
+ In a very basic configuration, OP-Addon will simply create the configured
+ number of circuits, and wait for incoming streams from applications to attach
+ them. However, if a user only wants to measure latencies of circuits, without
+ using them for anonymizing any traffic, she can make use of 'testing_mode'.
+ When 'testing_mode' is set to 'yes', one can specify 'num_rtt_test' (int), as
+ the number of latency tests that should be performed on each successfully
+ created circuit before actively closing it again. The mean value of the
+ results of these measurings is written to a file, together with the setup
+ duration of the specific circuit. Further 'num_records' specifies the total
+ number of circuits that is to be tested, before stopping the actual
+ application. 'Testing_mode' is not useful for transporting user traffic,
+ since circuits often dissapear unexpectedly, after 'num_rtt_tests' rounds
+ of measurings are finished.
+
+ If 'testing_mode' is set to 'no', we are in user mode. In user mode, OP-Addon
+ simply maintains the specified amount of circuits, created with the
+ configured method at every time, waiting to handle incoming user streams. One
+ can optionally specify, that the circuits shall be 'pinged' with any
+ configurable frequency (see 5.), so a ranked list of the circuits will be
+ maintained. Incoming user streams are then attached to the first suitable
+ circuit on this list. In both of the modes, OP-Addon will record statistics
+ on the created circuits to a file, including the median and mean setup
+ duration, min/max values and the number of failures that occurred during
+ circuit setups, as well as on already established circuits.
+
+4. Path selection configuration (sections NODE_SELECTION and GEOIP):
+
+ ** NOTE THAT MAKING USE OF CUSTOMIZED METHODS OF PATH SELECTION FOR
+ ANONYMIZING TCP-TRAFFIC MAY WEAKEN YOUR ANONYMITY AND SECURITY
+ COMPARED TO THE METHODS USED IN THE DEFAULT IMPLEMENTATION! **
+
+ The employed method of path selection can be freely configured using the
+ options from the sections NODE_SELECTION and GEOIP. Internally this is done
+ by combining arbitrary restrictions on the selection of single nodes, as well
+ as on complete paths. It is possible to choose from different node generators
+ and node/path restrictions by changing options in the configuration. Some of
+ the implemented restrictions make use of geolocation-data (using the geoip
+ library for Python from http://www.maxmind.com) to consider the location of
+ routers while choosing. This can be used to ensure a specific geographic
+ (non-)diversity of the routers in a path. But it is also possible to apply
+ any non-geographic restrictions, like explicitly specifying an exit node to
+ be used, or the length of the generated paths, as an example of a path
+ restriction. The following is a list of already implemented generators and
+ restrictions that can be configured using the following options from the
+ config-file:
+
+ General:
+ * pathlen: specify the number of hops to be used in paths
+ * min_bw: specify a minimum bandwidth
+ * exit_node: specify an exit node explicitly by nickname or IDhex
+ * use_guards: choose guards on the entry positions (yes|no)
+
+ NodeGenerators:
+ * uniform: choose uniformly (yes|no), can be combined with
+ * ordered_exits: choose exits from an ordered list
+ * uniform=no: choose by weighting advertised bandwidths
+
+ GeoIP:
+ * unique_country:
+ - 'yes' will enforce distinct countries for all hops in a path
+ - 'no' will put all hops in the same country,
+ - comment out means do not care
+ * entry_, middle_, exit_country: specify countries for positions
+ * max_crossings:
+ - 1-n specifies the max number of continent hops in a single path
+ - 0 will choose all hops on different continents
+
+ To extend the path selection features or to add new restrictions to be
+ applied to single nodes or complete paths, one can easily design and
+ implement new Node or PathRestrictions using the existing interfaces from
+ TorFlow.
+
+5. Latency measurements (section RTT):
+
+ It is possible to use OP-Addon to measure latencies of complete circuits, as
+ well as of single links between routers. By setting 'measure_circs' to 'yes',
+ OP-Addon will ping the complete circuits that are currently available with a
+ frequency that is specified by 'frequency' (in seconds given as float).
+ Additionally an initial interval needs to be specified, that shall be waited,
+ before triggering the first ping. Since most of the circuit creations need
+ less then 6 seconds, something like 10 seconds will be a safe value. Further
+ OP-Addon can be configured to close a circuit after n timeouts experienced
+ during measurement, where n is configured using 'timeout_limit'.
+
+ Measurements of RTTs are done by sending a relay connect cell, heading to a
+ destination that the exit policy of last router in the path will surely deny.
+ This destination is set in 'ping_dummy_*' options and the values in
+ pathrc.example are working well (127.0.0.1 and port 100). Since OP-Addon will
+ try to connect somewhere over Tor, also the Tor SOCKS-host and -port need to
+ be specified (mostly 127.0.0.1 and 9050).
+
+6. Circuit creation based on measured latencies (section MODEL):
+
+ Because of the leaky-pipe circuit topology in Tor, it is possible to address
+ every hop in a created circuit as the exit node for a stream. OP-Addon
+ implements a technique to measure and store RTTs of single links between
+ routers, by using every hop in a path as the exit once. The subtracted
+ results of this measurements are stored in a graph model that represents the
+ currently known subnet of a client. Setting 'network_model' to 'yes' will
+ enable this measurings and optionally circuit creation from the network model.
+ The 'max_rtt' option lets users specify a maximum rtt value to choose only
+ paths below this threshhold (seconds given as float, e.g. 0.5). The actual
+ selection from all suitable paths, that can currently be found in the model,
+ is done in a probabilistic way, weighting path proposals by their
+ (summed up) latencies, combined with the minimum advertised bandwidth of the
+ routers in the path. Using another option ('min_proposals'), OP-Addon will
+ begin to create circuits from the model only if there are 'min_proposals'
+ suitable path proposals found, satisfying the configured rtt-threshhold.
+
+ If the intension is to grow a network model only, without creating circuits
+ based on it, set 'min_ratio' to 1. 'min_ratio' defines the ratio of available
+ circuits that were *not* created based on measurings. Setting it to 0.5 will
+ enforce that at most 50% of the circuits in the pool were created from the
+ model at every time. This can ensure steady growing of the network model,
+ while already choosing paths from it for building circuits. Setting
+ 'min_ratio' to 0 will lead to circuits created from the model only. This
+ might be useful, if one wants to use a model, but not to extend or refresh it
+ anymore. The regular circuits are created using the parameters defined in
+ section 4.
+
+###############################################################################
+
+7. Implementing custom tests and measurings:
+
+ Anybody who wants/needs to implement his/her own custom measurings or
+ performance tests, probably will need to write an event handler that extends
+ from the existing classes in PathSupport.py, similar to the PingHandler
+ contained in OP-Addon. Therefore consider CircuitHandler, which is a class
+ that simply maintains a pool of circuits of configurable size, created with
+ any given method depending on the configuration. The StreamHandler class is
+ extending from the CircuitHandler and generally handles the attaching of
+ streams to circuits from the pool. You therefore might want to extend from
+ the StreamHandler for implementing your own tests.
+
+###############################################################################
+
+8. Instructions to get OP-Addon:
+
+ OP-Addon is part of the 'TorFlow' project that is hosted within the Tor
+ subversion. To check out the latest revision, 'cd' to the directory where
+ you want to install and type:
+
+ svn checkout https://tor-svn.freehaven.net/svn/torflow/trunk torflow
+
+###############################################################################
+
+9. Prerequisites and instructions to run OP-Addon:
+
+ Note that Linux is the only operating system, that OP-Addon was tested on
+ until now, but it might also run on other platforms. Let me know, if you
+ experimented with Windows or any other OS.
+
+ To run OP-Addon, you will need a Python interpreter and a running Tor client
+ with the ControlPort set (control port authentication is currently not yet
+ supported). Note that if you plan to measure latencies of single links
+ between routers, you need to compile the Tor client from source and to apply
+ a patch that allows to measure the latency from the proxy to the first hop
+ ('one-hop.diff' is included in the distribution in the '/tordiffs'-folder).
+
+ To make use of the complete functionalities, it is further necessary to
+ install the following Python libraries:
+
+ - GeoIP [http://www.maxmind.com/app/python]
+ - NetworkX [https://networkx.lanl.gov]
+ - SocksiPy [get it from http://socksipy.sourceforge.net/]
+
+ On Debian systems, the first two libraries can be installed by simply running:
+
+ apt-get install python-geoip networkx
+
+ To run OP-Addon, simply 'cd' to the installation directory and start the
+ script by calling:
+
+ ./op-addon.py [config-file]
+
+ If no config-file is given, OP-Addon will try to find 'pathrc.example',
+ which is included in the distribution. It is intended to be copied and
+ modified though.
+
+###############################################################################
+(c) 2007 Johannes Renner (renner <AT> i4.informatik.rwth-aachen.de)
More information about the tor-commits
mailing list