ChangeLog for #11290.
[flashproxy.git] / README
1 == Quick start for users
2
3 You must have a version of Tor that supports pluggable transports. This
4 means version 0.2.3.2-alpha or later.
5
6 All the flashproxy programs and source code can be downloaded this way:
7         git clone https://git.torproject.org/flashproxy.git
8 But as a user you only need these files:
9         https://gitweb.torproject.org/flashproxy.git/blob_plain/HEAD:/flashproxy-client
10         https://gitweb.torproject.org/flashproxy.git/blob_plain/HEAD:/torrc
11
12 You must be able to receive TCP connections; unfortunately means that
13 you cannot be behind NAT. See the section "Using a public client
14 transport plugin" below to try out the system even behind NAT.
15
16 Run Tor using the included torrc file:
17         $ tor -f torrc
18 By default the transport plugin listens on Internet-facing TCP port
19 9000. If you have to use a different port (to get through a firewall,
20 for example), edit the ClientTransportPlugin line of the torrc to give a
21 different port number:
22         ClientTransportPlugin flashproxy exec ./flashproxy-client --register :0 :8888
23 If the flashproxy-client program is in a different directoy (after being
24 installed, for example), use the full path in the ClientTransportPlugin
25 line:
26         ClientTransportPlugin flashproxy exec /usr/local/bin/flashproxy-client --register
27
28 You should receive a flash proxy connection within about 60 seconds. See
29 "Troubleshooting" below if it doesn't work.
30
31
32 == Overview
33
34 This is a set of tools that make it possible to connect Tor through an
35 browser-based proxy running on another computer. The flash proxy can be
36 run just by opening a web page in a browser. Flash proxies are one of
37 several pluggable transports for Tor.
38
39 There are five main parts.
40 1. The Tor client, running on someone's localhost.
41 2. A client transport plugin, which is a program that waits for
42    connections from a flash proxy and connects them to the Tor client.
43 3. A flash proxy, which is a JavaScript program running in someone's web
44    browser.
45 4. A facilitator, which is a server that keeps a list of clients that
46    want a connection and assigns those addresses to proxies.
47 5. A Tor relay running a server transport plugin capable of receiving
48    WebSocket connections.
49
50 The purpose of this project is to create many ephemeral bridge IP
51 addresses, with the goal of outpacing a censor's ability to block them.
52 Rather than increasing the number of bridges at static addresses, we aim
53 to make existing bridges reachable by a larger and changing pool of
54 addresses.
55
56
57 == Demonstration page
58
59 This page has a description of the project; viewing it also turns your
60 computer into a flash proxy as long as the page is open.
61
62 http://crypto.stanford.edu/flashproxy/
63
64
65 == Troubleshooting
66
67 Make sure someone is viewing http://crypto.stanford.edu/flashproxy/, or
68 another web page with a flash proxy badge on it.
69
70 You can add the --log option to the ClientTransportPlugin command line
71 in order to save debugging log messages.
72
73 If tor hangs at 10% with these messages:
74         [notice] Bootstrapped 10%: Finishing handshake with directory server.
75         [notice] no known bridge descriptors running yet; stalling
76 as a last resort you can try deleting the files in ~/.tor and
77 /var/lib/tor, and then restarting tor.
78
79 If tor apparently hangs here:
80         [notice] Bootstrapped 50%: Loading relay descriptors.
81         [notice] new bridge descriptor '...' (fresh)
82 wait a few minutes. It can take a while to download relay descriptors.
83
84 If you suspect that the facilitator has lost your client registration, you can
85 re-register:
86         $ flashproxy-reg-email
87         $ flashproxy-reg-http
88
89
90 == How to run a relay
91
92 Proxies talk to a relay running the websocket pluggable transport.
93 Source code and documentation for the server transport plugin are in the
94 Git repository at
95 https://git.torproject.org/pluggable-transports/websocket.git.
96
97
98 == How to put a flash proxy badge on a web page
99
100 Paste in this HTML where you want the badge to appear:
101
102 <iframe src="//crypto.stanford.edu/flashproxy/embed.html" width="80" height="15" frameborder="0" scrolling="no"></iframe>