### PROXY65 README ###

Code Author:   Dave Smith <dizzyd@jabber.org>
Doc Author:    Peter Saint-Andre <stpeter@jabber.org>
Doc Version:   1.0
Last Updated:  2003-09-26


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 be usable with most Jabber 
server implementations and is not limited to the jabberd 1.4
server series.


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.0.7 or 
higher installed in order to run Proxy65. However, Python 2.3 
and Twisted 1.0.8 or higher are recommended to ensure optimal
performance.


3. INSTALLING PROXY65

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

  python setup.py install

This should 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. 

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 -no -f proxy65.tap

  or:

  twistd -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. 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!).


7. REQUESTING FEATURES AND REPORTING BUGS

Follow the links at the project homepage:

  http://proxy65.jabberstudio.org/

Enjoy!

