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

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).
Note, this option is BAD! Don't use it unless you really don't care
about the passport accounts that will be used on this server. Try to
fix your curl certificates, there should be a certificate bundle
somewhere around curl-prefix/share/curl/curl-ca-bundle.crt
(I'm talking about the curl client certificates that are used to connect
to Microsoft Passport servers, not your Jabber server certs. MSN-t doesn't
care about the latter)

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 "-L /sw/lib -lcurl" into platform-settings for
Jabberd, and to then 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. :)
Please follow the instructions in the "Debugging MSN-t" section to know what
information I'll need to help you.

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.




Debugging MSN-t with GDB
----------------------------------------

Please follow these steps when reporting a crash with MSN-t

* Start MSN-t like you usually do, except append -D 2> stderr.log > stdout.log
to the end, eg
./jabberd -H /path/to/jabber -c msnt.xml -D 2> stderr.log > stdout.log

* Find the PID of your current MSN-t, sometimes in /var/run/jabber-msn.pid
or perhaps try 'ps aux|grep msn' should give it to you, eg 953

* Start gdb (type gdb at a command prompt)

* From the gdb prompt type
attach MSN-t_PID
or with the example above, attach 953
You will be returned to the gdb prompt

* The MSN-t process will freeze after this, so it's important that you
immediately type the command "continue" into the gdb prompt to
resume it's execution

* When/if MSN-t crashes, you will be returned to the gdb prompt, type
bt
to get a backtrace, (there may be more than one page, in which case you
will be instructed to press enter to continue scrolling)


Please mail me the backtrace, along with the stderr.log and stdout.log files.
Please compress them first.
Note: these WILL have passwords, account info and messages in them, just a
warning. I will respect your privacy and not use (or even look at when
possible) any of this information.

Note, if stderr.log and stdout.log are really huge (even after compression),
just send the last thousand lines or so, eg

tail -n 1000 stderr.log stderr-small.log

Then compress and mail those instead. Thanks

My email address is james@delx.cjb.net




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"

