### PROXY65 README ###

Code Author:   Dave Smith <dizzyd@jabber.org>
Doc Author:    Peter Saint-Andre <stpeter@jabber.org>
Doc Version:   1.0
Last Updated:  2004-05-20


1. INTRODUCTION

Proxy65 is a server-side component that enables you to add a 
SOCKS5 bytestreaming service to a standard Jabber server, 
mainly to be used for out-of-band file transfer. For a full
definition of the functionality, please read JEP-0065:

   http://www.jabber.org/jeps/jep-0065.html

Proxy65 runs as an "external component": i.e., it uses the 
over-the-wire API for server-side components documented in 
JEP-0114. Therefore it should work with most Jabber server 
implementations and is not limited to the jabberd 1.4 server 
series.

This README documents version 1.0 of Proxy65.


2. SOFTWARE REQUIREMENTS

Proxy65 is written in Python and built on top of the Twisted 
framework:

  http://www.twistedmatrix.com/

At a minimum, you MUST have Python 2.2 and Twisted 1.1.0 or 
higher installed in order to run Proxy65. 


3. INSTALLING PROXY65

Unzip the Proxy65 code into your preferred directory (it does
not need to be installed into your Jabber server directory); 
this will create a proxy65/ subdirectory. Type 'cd proxy65' to 
move to that directory.

As root or using sudo, type the following at the command line:

  python setup.py install

This will install the Python files you need into your Python
distribution.

If you want to install Proxy65 somewhere else, refer to:

  http://www.python.org/doc/current/inst/inst.html


4. CONFIGURING PROXY65

Next, update your server configuration. In this README, we use
a jabberd 1.4 XML file as our example, but you should be to add 
the correct configuration to other servers as well (refer to the 
documentation for your server of choice; remember that it must
support the Jabber component protocol documented in JEP-0114).

For jabberd 1.4, add an appropriate service line to the <browse> 
section of your jabber.xml file's JSM config:

  <jsm>
    <browse>
      ...
      <service jid="proxy65.yourhostname.tld" name="SOCKS5 Bytestream Service"/>
      ...
    </browse>
  </jsm>

You do not have to name it "proxy65", it can be anything you'd
like. However, it MUST be a fully qualified domain name if you
want people from outside your domain to use it (which is usually
the point of running a bytestreams service).

Then add an appropriate service definition of the kind you already
have for groupchat, gateways, JUD, and the like (this does not go
in the <jsm> section -- refer to the jabberd 1.4 admin guide or 
README for details):

  <service id="proxy65.yourhostname.tld">
    <accept>
      <ip>127.0.0.1</ip>
      <port>yourcomponentportnumber</port>
      <secret>yourproxysecret</secret>
    </accept>
  </service>

The 'id' SHOULD be the same as the 'jid' you provided above.

The port number can be anything you like (usually some high port
not registered with the IANA is a good idea). The port number you 
provide is the one over which server-to-component communications 
will occur, not the port used by clients when they connect to the 
bytestreams service.

The secret can be anything you like. 

The next step is to create a "Twisted Application Pickle", commonly
referred to as a TAP. A TAP is a file that holds configuration 
information for a Twisted application, so that you do not need to
create a separate configuration file.

First check to see that Twisted knows about your application by
typing the following command:

  mktap --help

Your application (proxy65) should show up in the output list.

If Proxy65 does not show up, check the python path in the following
two files:

  /usr/bin/mktap
  /usr/bin/twistd

If they are hardcoded to python2.2 but you have python2.3 installed,
change the python paths to point to "#!/usr/bin/python2.3".

Next, type:

  mktap proxy65 --help

You should see some nice help output:

  # mktap proxy65 --help
  Usage:    mktap [options] <command> [command options]
  Options:
      --jid=        [default: proxy65]
      --secret=
      --rhost=      [default: 127.0.0.1]
      --rport=      [default: 6000]
      --proxyip=
      --proxyport=  [default: 7777]
      --version
      --help        Display this help and exit.

Now you can run the 'mktap' command. This will generate the TAP
so that you don't have pass arguments to Proxy65 on the command
line whenever you want to start it.

The parameters have the following meaning:

  --jid         The JID of your Proxy65 service, just as it is 
                in your jabber.xml file or other config.
  --secret      The secret password used between your Jabber
                server and your Proxy65 component.
  --rhost       The IP address of your Jabber router (server).
  --rport       The port over which router-to-component traffic
                will be sent.
  --proxyip     The IP address used for SOCKS5 communications.
  --proxyport   The port used for SOCKS5 communications.

So, type something like this:

  mktap proxy65 --jid=proxy65.yourhostname.tld --secret=yourproxysecret --rhost=yourjabberdip rport=yourcomponentportnumber --proxyip=defaultnetworkIP --proxyport=7777

Here is an example:
 
  mktap proxy65 --jid=proxy65.localhost --secret=proxybaby --rhost=127.0.0.1 rport=7013 --proxyip=127.0.0.1 --proxyport=7777

You should now see a proxy.tap file in the directory where you
built the component.


5. RUNNING PROXY65

Now start your Jabber server, e.g., by running:

  ./jabberd/jabberd -D

You can now run your proxy server by typing:

  twistd -f proxy65.tap

  or:

  twistd -no -f proxy65.tap

(The -no option prevents the application from daemonizing itself.
Most server admins will want to run 'twistd -f proxy65.tap'.)

And voila! Proxy65 is running.


6. USAGE

At present, the main use for Proxy65 is file transfer between 
Jabber clients that are advanced enough to support the protocol
defined in JEP-0096:

   http://www.jabber.org/jeps/jep-0096.html

Note: when specifying the Jabber address of your proxy, you MUST
NOT include the port number. Jabber entities don't know anything
about port numbers, and if you specify a port number in your fine
new proxy's Jabber address, nothing will work and you will be 
tremendously disappointed.

File transfer is not the only use for Proxy65, although it is the
only use defined so far. Because Proxy65 is really just a generic 
bytestreaming proxy, it could be used for other applications (such 
as voice over IP using a relatively light protocol such as Speex). 
Look for more creative uses of Proxy65 in the future.


7. GETTING HELP

For help with Twisted, type 'man twistd'.

For help with Proxy65, contact either of the addresses listed
at the top of this README (use Jabber, you'll receive a faster 
reply!), or join the <jdev@conference.jabber.org> chatroom.


8. REQUESTING FEATURES AND REPORTING BUGS

Follow the links at the project homepage:

  http://proxy65.jabberstudio.org/

Enjoy!

