[tor-commits] [flashproxy/master] Make a more user-oriented README.
dcf at torproject.org
dcf at torproject.org
Sun Oct 16 23:35:24 UTC 2011
commit 1b3ca42959884dc165e874a5da19c640fcd9712b
Author: David Fifield <david at bamsoftware.com>
Date: Sun Oct 16 13:21:10 2011 -0700
Make a more user-oriented README.
Start with how to run the client software using the public servers, and
put the stuff about compiling SWF and running your own server at the
bottom.
---
README | 245 +++++++++++++++++++++++++++++++++++++++-------------------------
1 files changed, 151 insertions(+), 94 deletions(-)
diff --git a/README b/README
index fa6bf1d..bc09542 100644
--- a/README
+++ b/README
@@ -16,17 +16,149 @@ There are five main parts. Our terminology for each part is in quotes.
5. A Tor "relay," which is just a normal Tor relay except that its host
must also serve a Flash crossdomain policy.
-A proxy is capable of connecting to a client in two ways: Using a normal
-TCP connection; or over RTMFP, which requires Flash on the client but is
-capable of traversing NAT.
+The purpose of this project is to create many, generally ephemeral
+bridge IP addresses, with the goal of outpacing a censor's ability to
+block them. Rather than increasing the number of bridges at static
+addresses, we aim to make existing bridges reachable by a larger and
+changing pool of addresses.
+
== Demonstration page
+This page has a description of the project; viewing it also turns your
+computer into a flash proxy as long as the page is open. (Only if you
+have Adobe Flash Player installed.)
+
https://crypto.stanford.edu/flashproxy/
-== Quick start
-=== Building
+== Quick start for users
+
+You must have a version of Tor that supports the Socks4Proxy option.
+This means version 0.2.2.32 (released 2011-08-29) or later.
+
+All the flashproxy programs and source code can be downloaded this way:
+ git clone https://git.torproject.org/flashproxy.git
+But as a user you only need these files:
+ https://gitweb.torproject.org/flashproxy.git/blob_plain/HEAD:/connector.py
+ https://gitweb.torproject.org/flashproxy.git/blob_plain/HEAD:/torrc
+
+There are different ways to get connected, depending on whether you are
+able to receive direct TCP connections. The first method is preferred,
+if you are able to configure port forwarding or receive direct
+connections from the Internet.
+
+If you don't get a connection within 30 seconds or so, make sure someone
+with Flash Player is viewing https://crypto.stanford.edu/flashproxy/.
+There aren't yet enough operational proxies that one is available all
+the time.
+
+=== Direct TCP connection
+
+This is the preferred way to use a flash proxy when it's possible. The
+only communication your computer makes with a fixed IP address is
+registration with the facilitator: everything else happens over
+ephemeral proxies.
+
+1. Run the connector and instruct it to register with a public
+ facilitator.
+ $ python connector.py -f tor-facilitator.bamsoftware.com
+ By default the connector listens on Internet-facing TCP port 9000. If
+ you have to use a different port (to get through a firewall, for
+ example), give it on the command line like this (here using port
+ 8888):
+ $ python connector.py -f tor-facilitator.bamsoftware.com 127.0.0.1:9001 :8888
+2. Run Tor using the included torrc file.
+ $ tor -f flashproxy/torrc
+
+Watch the logs of connector.py and tor. From connector.py you are
+expecting output lines like this:
+ Remote connection from XXX.XXX.XXX.XXX:YYYYY.
+ Local connection from 127.0.0.1:ZZZZZ.
+ Linking 127.0.0.1:ZZZZZ and XXX.XXX.XXX.XXX:YYYYY.
+From tor you are looking for:
+ [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
+ [notice] Bootstrapped 100%: Done.
+
+=== Using a public connector
+
+Rather than running connector.py on your computer, you can use a public
+connector. This way is not as realistic because all your Tor traffic
+will first go to a public connector, which is at a fixed address and can
+be easily blocked. However this is an easy way to try out the system
+without having to do port forwarding.
+
+1. Edit the included torrc file to comment one line and uncomment
+ another:
+ # Socks4Proxy 127.0.0.1:9001
+ Socks4Proxy tor-facilitator.bamsoftware.com:9999
+2. Run Tor using the included torrc file.
+ $ tor -f flashproxy/torrc
+
+=== Using RTMFP
+
+This method uses a protocol called RTMFP to communicate through a NAT
+without port forwarding. However it uses a public server at a fixed
+address as an intermediary, so it can be easily blocked. (The
+intermediate server is operated by the flash proxy developers, not by
+Adobe as is usual with RTMFP.) This method also requires Flash Player on
+the Tor client, which the other methods don't.
+
+1. Download swfcat.swf from
+ https://crypto.stanford.edu/flashproxy/swfcat.swf
+ and save it locally. We will assume it is saved at
+ /home/user/flashproxy/swfcat.swf.
+2. Run the connector, without giving it a facilitator, and listening on
+ local ports only. In this configuration, it is the swfcat.swf program
+ that communicates with the facilitator, not the connector.
+ $ ./connector.py 127.0.0.1:9001 127.0.0.1:9002
+3. Open in a browser
+ file:///home/user/flashproxy/swfcat.swf?client=1&debug=1
+4. Run Tor using the included torrc file.
+ $ tor -f flashproxy/torrc
+
+You will see status messages in the swfcat.swf window.
+
+=== Troubleshooting
+
+Make sure someone is viewing https://crypto.stanford.edu/flashproxy/, or
+another web page with a flash proxy badge on it.
+
+Sometimes Tor can think that the bridge you reach through a proxy is
+unreachable after the proxy is disconnected, even if there is another
+proxy immediately available. If you are able to build Tor from source,
+try applying the patch patches/tor-ignore-bridge-failure.patch.
+ $ git apply ~/flashproxy/patches/tor-ignore-bridge-failure.patch
+or
+ $ patch -p1 < ~/flashproxy/patches/tor-ignore-bridge-failure.patch
+
+If tor hangs at 10% with these messages:
+ [notice] Bootstrapped 10%: Finishing handshake with directory server.
+ [notice] no known bridge descriptors running yet; stalling
+as a last resort you can try deleting the files in ~/.tor and
+/var/lib/tor, and then restarting tor.
+
+If tor apparently hangs here:
+ [notice] Bootstrapped 50%: Loading relay descriptors.
+ [notice] new bridge descriptor '...' (fresh)
+wait a few minutes. It can take a while to download relay descriptors.
+
+
+== How to put a flash proxy badge on a web page.
+
+Copy swfcat.swf to your server, then paste in this HTML:
+
+<object width="70" height="23">
+ <param name="movie" value="swfcat.swf">
+ <param name="flashvars" value="">
+ <embed src="swfcat.swf" width="70" height="23" flashvars=""></embed>
+</object>
+
+== For developers
+
+See design.txt for some more technical information.
+
+=== Building swfcat.swf
Download the (free software) Flex SDK.
http://opensource.adobe.com/wiki/display/flexsdk/Flex+SDK
@@ -36,7 +168,15 @@ To build, run
$ make
Copy the resulting swfcat.swf file to a web server.
-=== Connecting
+You can pass swfcat.swf the parameter debug=1 to see lots of debugging
+information.
+
+This is a good tutorial on ActionScript programming with the Flex tools,
+with sample code:
+ http://www.senocular.com/flash/tutorials/as3withmxmlc/
+ http://www.senocular.com/flash/tutorials/as3withmxmlc/AS3Flex2b3StarterFiles.zip
+
+=== Running a relay or facilitator
On the Tor relay, run
# ./crossdomaind.py
@@ -45,52 +185,11 @@ crossdomain policy, but the connector and facilitator have it built in.
On the facilitator, run
$ ./facilitator.py -r <relay-ip>
-The facilitator runs on port 9002 by default.
-
-In a browser somewhere, open swfcat.swf and pass it a parameters telling it
-which facilitator to use, for example
- http://www.example.com/swfcat.swf?facilitator=<facilitator-ip>:9002&debug=1
-
-There are two ways in which the client can receive connections: over TCP
-or RTMFP. TCP doesn't send traffic to anyone other than the facilitator
-and the proxy, but it only works if you have a public IP address. RTMFP
-coordinates connections using another server (which may be the same as
-the facilitator) and works when the client is behind a NAT.
-
-To connect with TCP, run
- $ ./connector.py -f <facilitator-ip>
-(If you are running the facilitator locally, be sure to use an external
-IP address, not 127.0.0.1.) The connector informs the facilitator that
-it wants a connection, then listens on 0.0.0.0:9000 and 127.0.0.1:9001.
-The proxy will connect on port 9000 and the local Tor will connect on
-9001.
-
-To connect with RTMFP, run
- $ ./connector.py 127.0.0.1:9001 127.0.0.1:9002
-and open in a browser
- http://www.example.com/swfcat.swf?client=1&facilitator=<facilitator-ip>:9002
-In this case, it is swfcat running in client mode that registers with
-the facilitator. The connector acts to join the local swfcat and the
-local Tor client.
-
-The client needs to be running a version of Tor that supports the
-Socks4Proxy configuration. This means version 0.2.2.1-alpha or
-later--not the current stable release.
-
-Start Tor with the following configuration (you can use the included torrc file):
- UseBridges 1
- Bridge 127.0.0.1:9001
- Socks4Proxy 127.0.0.1:9001
-
-If you see messages like
- [notice] Bootstrapped 10%: Finishing handshake with directory server.
- [notice] no known bridge descriptors running yet; stalling
-try deleting the files in ~/.tor or /var/lib/tor.
+You can use "tor1.bamsoftware.com" for <relay-ip>; it is already set up
+to serve a crossdomain policy. The facilitator runs on port 9002 by
+default.
-You will be able to see byte counts flowing in the browser window, and
-eventually be able to build a circuit.
-
-== Installing so as to restart at boot
+=== Installing so as to restart at boot
The directory init.d contains scripts to start the facilitator and
crossdomaind server on CentOS. "make install" copies files to /usr/local/bin.
@@ -109,7 +208,7 @@ crossdomaind server on CentOS. "make install" copies files to /usr/local/bin.
# chkconfig --add crossdomaind
# service crossdomaind start
-== Building the Cumulus RTMFP server
+=== Building the Cumulus RTMFP server
There is a free RTMFP rendezvous server called Cumulus. It is a
replacement for the Adobe Cirrus service at rtmfp://p2p.rtmfp.net/.
@@ -140,45 +239,3 @@ Follow these steps to install the Cumulus server. You need to open port
# cp flashproxy/init.d/cumulus /etc/init.d/cumulus
# chkconfig --add cumulus
# service cumulus start
-
-== Rationale
-
-The purpose of this project is to create many, generally ephemeral
-bridge IP addresses, with the goal of outpacing a censor's ability to
-block them. Rather than increasing the number of bridges at static
-addresses, we aim to make existing bridges reachable by a larger and
-changing pool of addresses.
-
-== Design notes
-
-Any Tor relay can be used, as long as it also serves a crossdomain
-policy.
-
-Clients register with the facilitator by sending an HTTP message:
- POST / HTTP/1.0\r\n
- \r\n
- client=<ip-addr/rtmfp-id>
-The flash proxy also gets a client address over HTTP:
- GET / HTTP/1.0\r\n
- \r\n
-The server sends back address specifications of a client and a relay in
-an HTTP respose.
- HTTP/1.0 200 OK\r\n
- \r\n
- client=<ip-addr/rtmfp-id>&relay=<relay-ip>
-
-== Embedding in HTML
-
-<object width="70" height="23">
- <param name="movie" value="swfcat.swf">
- <param name="flashvars" value="">
- <embed src="swfcat.swf" width="70" height="23" flashvars=""></embed>
-</object>
-
-== ActionScript programming
-
-A good tutorial on ActionScript programming with the Flex tools, with
-sample code:
-
-http://www.senocular.com/flash/tutorials/as3withmxmlc/
-http://www.senocular.com/flash/tutorials/as3withmxmlc/AS3Flex2b3StarterFiles.zip
More information about the tor-commits
mailing list