[Pkg-privacy-commits] [obfsproxy] 109/353: Improve the HOWTO guide.

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch master
in repository obfsproxy.

commit cb496333a41875330bb91c5a24f7f1b008107a36
Author: George Kadianakis <desnacked at riseup.net>
Date:   Tue Feb 5 15:26:09 2013 +0000

    Improve the HOWTO guide.
---
 doc/HOWTO.txt | 136 ++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 94 insertions(+), 42 deletions(-)

diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
index 5a38488..44e3b5e 100644
--- a/doc/HOWTO.txt
+++ b/doc/HOWTO.txt
@@ -1,55 +1,107 @@
-This is a guide on how to setup a pyobfsproxy obfs2 bridge. More
-documentation coming soon!
+This is a short guide on how to setup a pyobfsproxy obfs2/obfs3 bridge
+on a Debian/Ubuntu system.
 
-a)
-First clone and install pyptlib. It's a small Python library which
-implements the managed-proxy protocol of pluggable transports. You can
-find it here: https://gitweb.torproject.org/user/asn/pyptlib.git
+Step 0: Install needed dependencies
 
-Doing:
-$ sudo apt-get install python-setuptools
-$ git clone https://git.torproject.org/user/asn/pyptlib.git
-$ cd pyptlib && python setup.py install
-should be sufficient.
+ To use pyobfsproxy you will need git, Python (>= 2.7) and a couple of
+ python libraries. If you use Debian testing (or unstable), or a
+ version of Ubuntu newer than Oneiric, this is easy:
 
-You might need to run the 'python setup.py install' command as
-root. If you don't want to run it as root, you can use
-'python setup.py install --user' which will install pyptlib just for
-the current user.
+   # apt-get install git python2.7 python-setuptools python-crypto python-twisted python-argparse
 
-b)
-Now clone pyobfsproxy. You can find it here:
-https://gitweb.torproject.org/user/asn/pyobfsproxy.git
+ You will also need a development version of Tor. To do this, you
+ should use the following guide to install tor and
+ deb.torproject.org-keyring:
+ https://www.torproject.org/docs/debian.html.en#development
 
-Doing:
-$ sudo apt-get install python-crypto python-twisted python-argparse
-$ git clone https://git.torproject.org/user/asn/pyobfsproxy.git
-should do the trick.
+ You need Tor 0.2.4.x because it knows how to automatically report
+ your obfsproxy address to BridgeDB.
 
-c)
-Now give pyobfsproxy a little try to see that it works. For example:
 
-$ python obfsproxy.py --log-min-severity=debug obfs2 socks 127.0.0.1:5555
+Step 1: Install pyptlib
 
-If it gets into the event loop and starts listening for connections,
-you are OK. You can even run the (very simple for now) integration
-tests by doing:
+  You will also need pyptlib, a small library developed by the Tor
+  project for writing pluggable transports.
 
-$ cd obfsproxy/test/ && python tester.py
+    $ git clone https://git.torproject.org/pluggable-transports/pyptlib.git
+    $ cd pyptlib && python setup.py install
 
-d)
-Since pyobfsproxy runs it's time to point your ServerTransportPlugin
-to pyobfsproxy:
+  You might need to run the 'python setup.py install' command as
+  root. If you don't want to run it as root, you can use 'python
+  setup.py install --user' which will install pyptlib just for the
+  current user.
 
-"""
-ServerTransportPlugin obfs2 exec /usr/bin/python /home/user/pyobfsproxy/obfsproxy.py --log-file=/home/user/alog.log --log-min-severity=info managed
-"""
 
-This will start pyobfsproxy with 'obfs2', and will write an info-level
-log to /home/user/alog.log. The 'managed' that you see in the end of
-the line, is the same as the '--managed' in C-obfsproxy.
+Step 2: Install and test pyobfsproxy
+
+  Now it's time to fetch pyobfsproxy and test that it works:
+
+    $ git clone https://git.torproject.org/pluggable-transports/pyobfsproxy.git
+    $ cd pyobfsproxy
+    $ python obfsproxy/test/tester.py
+
+  If you got a message reporting that all tests finished successfully,
+  then pyobfsproxy works for you. Run the setup.py script so that
+  pyobfsproxy gets installed in your system:
+
+    # python setup.py install
+
+  You will probably want to run the setup.py script as root so that pyobfsproxy gets installed in /usr/local/bin.
+
+
+Step 3: Setup Tor
+
+  Edit your /etc/tor/torrc to add:
+
+    SocksPort 0
+    ORPort 443 # or some other port if you already run a webserver/skype
+    BridgeRelay 1
+    Exitpolicy reject *:*
+
+    ## CHANGEME_1 -> provide a nickname for your bridge, can be anything you like
+    #Nickname CHANGEME_1
+    ## CHANGEME_2 -> provide some email address so we can contact you if there's a problem
+    #ContactInfo CHANGEME_2
+
+    ServerTransportPlugin obfs2,obfs3 exec /usr/local/bin/pyobfsproxy managed
+
+  Don't forget to uncomment and edit the CHANGEME fields.
+
+
+Step 4: Launch Tor and verify that it bootstraps
+
+  Restart Tor to use the new configuration file. (Preface with sudo if
+  needed.)
+
+    # service tor restart
+
+  Now check /var/log/tor/log and you should see something like this:
+
+    Nov 05 16:40:45.000 [notice] We now have enough directory information to build circuits.
+    Nov 05 16:40:45.000 [notice] Bootstrapped 80%: Connecting to the Tor network.
+    Nov 05 16:40:46.000 [notice] Bootstrapped 85%: Finishing handshake with first hop.
+    Nov 05 16:40:46.000 [notice] Bootstrapped 90%: Establishing a Tor circuit.
+    Nov 05 16:40:48.000 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
+    Nov 05 16:40:48.000 [notice] Bootstrapped 100%: Done.
+
+  If Tor is earlier in the bootstrapping phase, wait until it gets to 100%.
+
+
+Step 5: Set up port forwarding if needed
+
+  If you're behind a NAT/firewall, you'll need to make your bridge
+  reachable from the outside world — both on the ORPort and the
+  obfsproxy port. The ORPort is whatever you defined in step two
+  above. To find your obfsproxy port, check your Tor logs for two
+  lines similar to these:
+
+    Oct 05 20:00:41.000 [notice] Registered server transport 'obfs2' at '0.0.0.0:26821
+    Oct 05 20:00:42.000 [notice] Registered server transport 'obfs3' at '0.0.0.0:40172
+
+  The last number in each line, in this case 26821 and 40172, are the
+  TCP port numbers that you need to forward through your
+  firewall. (This port is randomly chosen the first time Tor starts,
+  but Tor will cache and reuse the same number in future runs.) If you
+  want to change the number, use Tor 0.2.4.7-alpha or later, and set
+  "ServerTransportListenAddr obfs2 0.0.0.0:26821" in your torrc.
 
-e)
-This should be it. Hopefully you will see:
-"Registered transport 'obfs2' in '0.0.0.0:5541'"
-in your logs.

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/obfsproxy.git