PyMSNt Server Administrator Guide

This documentation is for version 0.11 of the transport.

Please visit http://delx.cjb.net/pymsnt to download the transport and see news updates.

Please visit the MSN Transport User's Guide if you are a Jabber user and want to talk to your MSN friends.

If you have any insights or comments to add to this page please let me know by email or Jabber: james@delx.cjb.net

Installation Guide

Instructions/suggestions for other servers and OSs are welcome

Basic Installation

Python

Make sure have installed Python 2.3 or newer (I have reports that some older versions work). Most distributions should handle this automatically for you.
- Mandrake:
```
urpmi python
```
- Debian:
```
apt-get install python
```
- Fedora:
```
yum install python
```
- Centos 4:
```
yum install python
```
- Suse:
```
yast -i python
```
- Darwin: You need fink unstable.
```
fink install python
```
  (Install Python with fink, because we will use other Python libraries from fink later)
- MS Windows: Download and run the binary installer from http://www.python.org. When complete, add the directory that python.exe is in to your PATH (look in Windows help for details on doing this)
- Others: Use your distribution's installation method, or download and compile the source from http://www.python.org
Twisted

Install the Twisted framework (library). Version 1.1 or newer should be fine. Please make sure you're using PyMSNt 0.9.3 or newer for Twisted 2.0 support.

If you're using Twisted 2.0, either grab the "Sumo" package (easiest), or make sure you download at least these modules: core, web, words
- Mandrake: You will need to download the pycrypto and python openssl RPMs and install them as well as twisted using urpmi. Unfortunately I cannot provide links. I know you can get them from Mandrake Club though.
- Debian sarge:
```
apt-get install python-twisted python-crypto python-pyopenssl python-imaging
```
- Debian:
```
apt-get install python-twisted python-twisted-words python-crypto python-pyopenssl python-imaging
```
- Fedora:
```
yum install python-twisted pyOpenSSL pycrypto
```
- Centos 4:
```
yum install python-twisted python-crypto pyOpenSSL
```
- Suse:
```
yast -i python-twisted python-openssl python-pycrypto
```
- Darwin:
```
fink install twisted-py23 pycrypto-py23 pyopenssl-py23
```
- MS Windows: Download and run the binary installers for Twisted, PyCrypto and PyOpenSSL from http://www.twistedmatrix.com
- Others: Use your distribution's installation method, or download (and compile when necessary) from Twisted, PyOpenSSL and PyCrypto
PyMSNt

Download PyMSNt from delx.cjb.net/pymsnt and decompress it to a suitable location.
Configure

Copy the file config-example.xml to config.xml and edit it to suit your environment.
Note, with older versions of PyMSNt you were supposed to edit config.py. This is NOT recommended in this version.
- The 'jid' setting should be the ID you want PyMSNt to take on the network. Example: 'msn.host.com'.
- The 'host' setting should be a public DNS or IP address of the server the transport is running on. This is needed for file transfer!
- The 'mainServer' setting should be the IP address or DNS of the main Jabber server. Default: '127.0.0.1'.
- The 'port' setting is the port that PyMSNt and the Jabber server agree to use to connect between them (more details on this below). Default: '5347'.
- The 'secret' setting should match the secret specified for component connections in your main Jabber server. It's a password that only the Jabber server and the transport must know.
- The 'website' setting should be a website to refer users to.
- There are other options in this file that are documented by comments. It is safe to leave them at the default values.
- Ensure that the transport can make outgoing connections on port 443 (HTTPS), 1863, as well as incoming connections on 8010 (for Jabber file transfers).
Spool directory

PyMSNt stores login information (MS Passport account, password and nick) in the spool directory. This directory should meet this conditions:
- be located in the same place as the README and TODO files
- be writeable by whatever system user will be running PyMSNt
- have the same name as the 'jid' value you specified above in config.xml. (for example: 'msn.host.com')
This directory will be automatically created for you if this is a fresh installation. If you are migrating from an older version of the transport (including the C version), you can copy your existing spool directory into the new location.
Don't forget to rename it to the 'jid' value you specified on config.xml
Configure Jabber server

Now you have to configure your Jabber server. The following section covers this in detail.
Start PyMSNt

Now you're ready to start PyMSNt for the first time:
```
./PyMSNt.py
```
It will connect to the Jabber server and serve the Discovery JID you specified. Note: PyMSNt does not implement the old and deprecated 'Browse' capacity, only the newer 'Discovery'.

On MS Windows you can run it by opening a DOS console in the PyMSNt directory and running "python PyMSNt.py"

You may wish to find a rc.d script to automatically start the transport on Linux, or to make the transport into a service on Windows.

Jabber Server Configuration

The instructions below assume you are running PyMSNt on the same machine as your main Jabber server

Jabberd1.4.x

If you are using Jabberd1.4.x then you need to add this to your jabber.xml file
```
  <service id="msn.host.com">
          <host>msn.host.com</host>
          <accept>
                  <ip>127.0.0.1</ip>
                  <port>5347</port>
                  <secret>secret</secret>
          </accept>
  </service>
```
Check that msn.host.com is the same as the 'jid' setting from config.xml and that 5347 is the same as the 'port' setting. Also 'secret' must correspond, and the 'mainServer' setting should be pointing to the same interface as the <ip/> tag is (in this example the loopback interface is used. So 'mainServer' would be '127.0.0.1').

You must also add this to the browse section of your jabber.xml file
```
 <service type="msn" jid="msn.host.com" name="MSN Transport">
   <ns>jabber:iq:register</ns>
   <ns>jabber:iq:gateway</ns>
 </service>
```
Once again, msn.host.com must correspond to the 'jid' setting in config.xml

Once you have made all these changes, restart your Jabberd1.4.x server, then start PyMSNt and it should all work.
Jabberd2

If you are using Jabberd2 then you shouldn't have to do much configuration. Make sure the 'mainServer' setting is the IP or DNS of your Jabber server, and leave the 'port' setting alone. Double-check that the secret for legacy components in router.xml (for Jabberd2) is the same as the secret setting in config.xml. That should be all. You don't even need to restart Jabberd2.

You may need to add the following to your Jabberd2 router-users.xml
```
<user>
	<name>msn.host.com</name>
	<secret>secret</secret>
</user>
```
If you are upgrading from the old C version of MSN-t then you need to remove the alias info in your router.xml and the item discovery info in your sm.xml for the old msn transport. These were needed for the old MSN-t, but Jabberd2 can automatically add the new PyMSNt to the browse lists.
ejabberd

To configure ejabberd for PyMSNt, as explained in ejabberd Guide:
1. Edit ejabberd.cfg.
2. In the section that says: '{listen,' add those two lines:
```
    {5347, ejabberd_service, [{host, "msn.host.com",
                               [{password, "secret"}]}]},
```
3. Restart ejabberd and you're done.
Wildfire

In the Wildfire administration console, click the Server tab, and then External Components. Enable external components and enter a port (default is 10015) and a default shared secret.

Use the port and secret in the PyMSNt config.xml to connect the transport to Wildfire

Clustering

More to be written... For now, have a look at the compjid option.

Tips

You can send 'end' to the transport's bare JID at any time to completely destroy your session.
You can specify the transport should use a different config file by passing the name of the file as an argument, eg
```
./PyMSNt -c /etc/jabber/pymsnt.xml &
```
If you are using multiple configurations it is recommended that you specify using absolute paths to the PID and spool settings in each of the configurations.
There are many settings in the config.xml file, have a look and see if any of them would be useful to you
The transport will try to talk to the user in their own language, provided their client sends a xml:lang attribute. You can read about this in the XMPP RFCs. If you want your language to be included, please have a look at lang.py, make a translation and send it to me.
On Unix platforms sending a SIGHUP will cause the transport to reload the config file and close & open the debug.log file, eg
```
kill -1 `cat PyMSNt.pid`
```
Run in the directory that PyMSNt.pid is in. This will send a SIGHUP signal to the transport.
If you want your transport to be accessible to other Jabber servers then make sure the JID is resolvable by DNS. Note that not having a resolvable DNS doesn't prevent a determined server admin from using your gateway.
To disable file transfer, simply comment out the ftJabberPort and ftOOBPort options. This will disable file transfer in both directions.
To keep the size of the avatar spool directory down, try adding a command like this to your cronfile:
```
find /path/to/msn.host.com/avatars -atime +30 -delete
```
To get the latest version of the transport, run this command:
```
svn co svn://delx.cjb.net/pymsnt/trunk pymsnt
```

Possible problems:

On MS Windows, if you can't run PyMSNt, make sure you have Python installed correctly (as well as all of Twisted and PyCrypto/PyOpenSSL), and that python.exe is in your PATH (see above).
See the User's Guide to PyMSNt for more details on using the transport
Do not use Twisted 2.0.0. It is buggy!
If you are upgrading from the CMSN-t and your Jabber server has been running prior to about November 2003 then some of your users' contact lists may have msn.host.com/registered in them. These users should delete the transport from their list, and reregister it. There is no need to delete the transport users (so they will not have to reauthorise any contacts).
Under some circumstances CMSNt will split your spool directory into many subdirectories. To use this spool directory with PyMSNt, you can first run this command in your current spool directory:
```
find -name '*.xml' -exec cp -v {} fixed_msn.host.com \;
```

Bug reports and comments go to James Bunton

I'll gladly help you with any problems, but please look through this whole page, the README & config.xml files first.

PyMSNt Server Administrator Guide

Installation Guide

Basic Installation

Python

Twisted

PyMSNt

Configure

Spool directory

Configure Jabber server

Start PyMSNt

Jabber Server Configuration

Jabberd1.4.x

Jabberd2

ejabberd

Wildfire

Clustering

Tips

Possible problems: