MSN Transport (CVS)
===================
http://msn-transport.jabberstudio.org/

Features
--------

- MSN protocol 8

Requirements
------------

- jabberd 1.4.x source and header files (-dev)
- libcurl2-ssl with headers (-dev)

Building from tarball
---------------------

  Run "./configure --with-jabberd=/path/to/jabberd" to regenerate the Makefile
  Run "make" to build the transport

  Other configure options are --with-curl-includes, --with-curl-libs and
  --with-pth to specify the path to curl/curl.h, libcurl.a and pth.h
  There is also --ignore-ssl to compile against a version of curl with no
  SSL support (only use this if you know what you're doing)

Building from CVS
-----------------

  Make sure you have the auto tools installed (autoconf 2.50+ and automake 1.4+)
  Run "./bootstrap" to generate the configure file
  Then, to just build the transport:
   Run "./configure --with-jabberd=/path/to/jabberd" to regenerate the Makefile
   Run "make" to build the transport
  To create a tarball for distribution:
   Run "./configure --with-jabberd=/path/to/jabberd"
   Run "make dist"


Building the transport module
-----------------------------

Go to the transport's main directory and
 ./configure --with-jabberd=/path/to/jabberd
 make

You should get a
 src/msntrans.so
then (MSN-t module for jabberd 1.4.x).


Overview
--------

MSN-t is a module for jabberd 1.4.2.

MSN-t (or precisely spoken, jabberd 1.4.x running the MSN-t
module) links to the main Jabber server via the connect/accept
mechanism. This means you can use the transport with every 
Jabber server implementation (be it jabberd 1.4.x, jabberd 2,
WPJabber or a commercial server) that can accept TCP
connections from external components.


Configuration
-------------

1. Main Jabber server configuration files

In order to have your main Jabber server accept connections from the
transport's jabberd, you have to configure it accordingly.

If you run jabberd 1.4.x as your main server , add the following to
the <service> section of its configuration file.

 <service id="msnlinker">
   <host>msn.localhost</host>
   <host>conference.msn.localhost</host>
   <accept>
     <ip>127.0.0.1</ip>
     <port>1234</port>
     <secret>test</secret>
   </accept>
 </service>

Be sure to replace "localhost" with the full host name of your server
if you want users of other Jabber servers to be able to use this
transport. Also, the host name of the transport has to be resolveable
via DNS then.
If you do not want users of other Jabber server to be able to use
your server's transport, just add the hostnames of the transport to
/etc/hosts.
In every case all hostnames must resolve on the main Jabber server's
machine, e.g. "ping msn.localhost" must run fine.

In order to advertise the transport's services to the Jabber clients,
add the following to the <browse> section of the main jabberd 1.4.x
configuration file.

 <service type="msn" jid="msn.localhost" name="MSN Transport">
   <ns>jabber:iq:gateway</ns>
   <ns>jabber:iq:register</ns>
 </service>


2. MSN module configuration files

An example configuration file is included (msnt.xml), modify it as
needed.


Running
-------

- make sure the main Jabber server is running
- chdir to the main directory of the tarball
- run "jabberd -c msnt.xml"



Troubleshooting
---------------

Firstly, if you run into trouble, add "-D" for debug output. Have
a look through that and it might tell you the problem. If not,
read below.

If the transport fails to connect to the main Jabber server,
make sure "telnet 127.0.0.1 1234" (or whatever values you used
in the configuration files) is working on the machine you try
to start the transport on.
You must also be able to resolve msn.yourhost from the machine
the main Jabberd is running on.

If Jabberd has trouble finding it's files, try running
"jabber -c msnt.xml -H /path/to/jabber" to specify the home
directory for jabber to run from.

If you get "Error processing packet", perhaps accompanied by a Curl
warning during login/registration with the transport, try setting
the <insecureSSL/> option (look in the example config file).

There also may be a problem with your version of Curl, check it has
SSL support compiled in (you can do this with the curl-config command).
I've also heard of bugs in versions of Curl less than 7.10.7, so try
that version or newer.

If all else fails, have a look at the Curl error message, do "man curl"
to get a list of what the different error codes mean, you may be able
to fix the problem like that. If not, run in debug mode and mail the
entire session off to me.

If you have problems with conferencing check that the domain you are using
for msn conference resolves properly from the main Jabberd.
eg, ping conference.msn.yourhost
Double check your configuration matches the examples provided.
In particular, many people get "Circular reference detected" as an error,
this can be caused by having a <host>msn.yourhost</host> tag in msnt.xml

To compile on OSX, do everything as normal, but the final command (used
to create msntrans.so) will fail. Change into the src directory, then
re-run the command, but replace "-shared" with
"-bundle -undefined suppress -flat_namespace" 
You may also have to add -lcurl into platform-settings for Jabberd, and
recompile that.

Another thing that solved a mysterious crash somebody was having, was to
simply grab a fresh tarball of Jabberd and msn-transport, and recompile
them both. So, try that for you.

Good luck trouble-shooting!

Once again, if all else fails, and you cannot find/fix the problem, feel
free to mail me and ask. It may be a bug. :)

Also, if you have a problem that you solve and you think it may be useful
for others to know how to also, please mail me and let me know. Thanks.


Notes
-----

MSN-t uses TCP port 1863 for outgoing connections so you have to open
this port if you use a firewall. No incoming connections are used.

As of MSN-t 1.2.8 all spool files _must_ be lowercase. If a spool file
has any uppercase letters in it, that user will not be able to user MSN-T
until they re-register the transport. To lowercase all the spool files,
change into the spool directory for MSN-T and run this command

"for i in *.xml; do mv "$i" `echo $i | tr '[A-Z]' '[a-z]'`; done"

