-- What is Extended ORPort.

  It's an extra Tor port (like ORPort) that allows server pluggable
  transport proxies (like obfsproxy) to exchange metadata with Tor.

-- Why do I need it?

  Through the Extended ORPort, an obfuscated bridge is able to learn the
  IP addresses of its clients (which otherwise would only be visible to
  the pluggable transport proxy). This is essential for keeping
  statistics.

  In the future, using the Extended ORPort, Tor will be able to pass
  rate-limiting and bandwidth accounting advice to pluggable transport
  proxies and also further guide their behavior when needed.

-- Why am I reading this?

  We recently implemented the Extended ORPort and a subset of its
  proposed features.

  It's not in any released Tor version yet (and probably won't be for a
  while). It's a fairly big patchset and it needs testing.

  The idea is that if you are into trying experimental features and
  compiling software, you can help us with testing, which would help a
  lot.

  Please note that these instructions are not robust or user-friendly,
  and you are expected to understand basic Tor configuration, and how
  programs are compiled, installed and ran, to be able to follow then.

-- What is its status?

  (You can skip this section if you are not interested in Tor internals.)

  There are currently two Tor proposals related to the Extended ORPort:

  https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/196-transport-control-ports.txt

  Proposal 196 defines the Extended ORPort (and its friend
  TransportControlPort).

  https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/217-ext-orport-auth.txt

  Proposal 217 defines an authentication scheme (similar to the
  ControlPort's cookie authentication scheme) to protect the Extended
  ORPort. All connections to the Extended ORPort need to authenticate
  using this scheme. This allows only pluggable transport proxies
  running on the same machine to access the Extended ORPort.

  Till now we've implemented proposal 217 and a subset of 196.
  Specifically, from 196 we've only implemented the USERADDR command,
  which allows pluggable transport proxies to pass the IP addresses of
  their clients to Tor. That's quite useful, since it will allow us to
  include pluggable transport statistics in metrics.torproject.org
  (currently, obfsproxy users are not counted anywhere, and we really
  don't know how many people are using obfsproxy).

  The next step is to implement
  https://trac.torproject.org/projects/tor/ticket/5040
  which allows us to provide even more fine-grained statistics (for
  example, finding out which pluggable transports are more popular than
  others).

-- OK. I like. How do I test?

  The Extended ORPort has two components: the client-side component (in
  your pluggable transport proxy) and the server-side component (in
  tor). Since the Extended ORPort is not implemented in any released
  versions of Tor or obfsproxy, you will need to use development git
  branches. This is pretty easy if you are familiar with git.

  By the way, in this guide we are going to use *pyobfsproxy* instead
  of obfsproxy. pyobfsproxy is an experimental python port of
  obfsproxy which is under development, and for better or for worse,
  the Extended ORPort implementation was written in pyobfsproxy.

  Let's begin.

  ~ Install Tor with Extended ORPort support:

    Clone my Tor repository, and switch to the Extended ORPort branch:

    $ git clone -b bug4773_test https://git.torproject.org/user/asn/tor.git

    Now compile Tor:
    $ ./autogen.sh && ./configure && make

    If the compilation finished successfully, you should have a Tor binary
    in ./src/or/tor.

    To use the Extended ORPort, you will need a bridge torrc with the
    following extra option:
    """
    ExtORPort 30701
    """
    ('30701' is the TCP port number, which can be changed.)

  ~ Install pyobfsproxy with Extended ORPort support:

    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

    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.

    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.

    b)
    Now clone the Extended ORPort branch of pyobfsproxy. You can find
    it here: https://gitweb.torproject.org/user/asn/pyobfsproxy.git

    Doing:
    $ sudo apt-get install python-crypto python-twisted python-argparse
    $ git clone -b bug4773_test https://git.torproject.org/user/asn/pyobfsproxy.git
    should do the trick.

    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

    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:

    $ cd obfsproxy/test/ && python tester.py

    d)
    If pyobfsproxy seems to run properly, it's time to register it to
    tor. Add the following line to your torrc:
    """
    ServerTransportPlugin obfs2 exec /usr/bin/python /home/user/pyobfsproxy/obfsproxy.py --log-file=/home/user/alog.log --log-min-severity=info managed
    """
    Of course, change the filesystem paths accordingly. You can also
    tweak the command line options if you feel like it.

    The above line will start pyobfsproxy with the 'obfs2' transport,
    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.

    The above instructions were based on:
    https://gitweb.torproject.org/user/asn/pyobfsproxy.git/blob/HEAD:/doc/HOWTO.txt

  After adding the ServerTransportPlugin line to your torrc and
  launching Tor, you should see the following lines in your logs:
  "Opening Extended OR listener on 127.0.0.1:30701"
  and
  "Registered transport 'obfs2' in '0.0.0.0:5541'"

  If you don't see both of these lines, something probably went wrong
  and hopefully the problem should be noted in your logs.

-- How can I test that this thing actually works?

  There are a couple of ways: You can enable debug-level logging in
  tor, and grep your logs for "Extended ORPort"-related
  logs. Similarly, you can also enable logging in obfsproxy.

  Also, after 24 hours, your $DataDirectory/stats/bridge-stats file
  should contain client GeoIP stats. For example, mine looks
  like this:
  """
  bridge-stats-end 2012-12-05 12:23:22 (86400 s)
  bridge-ips cn=8,il=8,ir=8
  bridge-ip-versions v4=8,v6=0
  """

-- Notes:

  If you have configured Tor to switch to another user (using the User
  option), your pyobfsproxy directory needs to be executable and
  readable by that user.

  If you find a bug, please open a ticket in trac.torproject.org.