code.delx.au - pymsnt/blob - docs/server.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
   6 <link rel="stylesheet" href="style.css" type="text/css"/>
   7 <title>PyMSNt Server Administrator Guide</title>
   8 </head>
   9
  10 <body>
  11
  12 <h1>PyMSNt Server Administrator Guide</h1>
  13
  14
  15 <p>This documentation is for version 0.11 of the transport.</p>
  16 <p>Please visit <a href="http://delx.cjb.net/pymsnt">http://delx.cjb.net/pymsnt</a> to download the transport and see news updates.</p>
  17 <p>Please visit the <a href="http://delx.cjb.net/pymsnt/docs/user.html">MSN Transport User's Guide</a> if you are a Jabber user and want to talk to your MSN friends.</p>
  18 <p>If you have any insights or comments to add to this page please let me know by email or Jabber: james&#64;delx.cjb.net</p>
  19
  20 <hr/>
  21
  22
  23 <h2>Installation Guide</h2>
  24
  25 <p>Instructions/suggestions for other servers and OSs are welcome</p>
  26
  27 <h3>Basic Installation</h3>
  28
  29 <ol>
  30
  31 <li><h4>Python</h4>
  32 <p>
  33 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.
  34 </p>
  35 <ul>
  36 <li>Mandrake: <pre>urpmi python</pre></li>
  37 <li>Debian: <pre>apt-get install python</pre></li>
  38 <li>Fedora: <pre>yum install python</pre></li>
  39 <li>Centos 4: <pre>yum install python</pre></li>
  40 <li>Suse: <pre>yast -i python</pre></li>
  41 <li>Darwin: You need <a href="http://finkproject.org">fink</a> unstable. <pre>fink install python</pre> (Install Python with fink, because we will use other Python libraries from fink later)</li>
  42 <li>MS Windows: Download and run the binary installer from <a href="http://www.python.org">http://www.python.org</a>. When complete, add the directory that python.exe is in to your PATH (look in Windows help for details on doing this)</li>
  43 <li>Others: Use your distribution's installation method, or download and compile the source from <a href="http://www.python.org">http://www.python.org</a></li>
  44 </ul>
  45 </li>
  46
  47 <li><h4>Twisted</h4>
  48 <p>
  49 Install the Twisted framework (library). Version 1.1 or newer should be fine.
  50 Please make sure you're using PyMSNt 0.9.3 or newer for Twisted 2.0 support.
  51 </p>
  52 <p>
  53 If you're using Twisted 2.0, either grab the &quot;Sumo&quot; package (easiest),
  54 or make sure you download at least these modules: core, web, words
  55 </p>
  56 <ul>
  57 <li>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.</li>
  58 <li>Debian sarge: <pre>apt-get install python-twisted python-crypto python-pyopenssl python-imaging</pre></li>
  59 <li>Debian: <pre>apt-get install python-twisted python-twisted-words python-crypto python-pyopenssl python-imaging</pre></li>
  60 <li>Fedora: <pre>yum install python-twisted pyOpenSSL pycrypto</pre></li>
  61 <li>Centos 4: <pre>yum install python-twisted python-crypto pyOpenSSL</pre></li>
  62 <li>Suse: <pre>yast -i python-twisted python-openssl python-pycrypto</pre></li>
  63 <li>Darwin: <pre>fink install twisted-py23 pycrypto-py23 pyopenssl-py23</pre></li>
  64 <li>MS Windows: Download and run the binary installers for Twisted, PyCrypto and PyOpenSSL from <a href="http://www.twistedmatrix.com">http://www.twistedmatrix.com</a></li>
  65 <li>Others: Use your distribution's installation method, or download (and compile when necessary) from <a href="http://www.twistedmatrix.com">Twisted</a>, <a href="http://pyopenssl.sourceforge.net/">PyOpenSSL</a> and <a href="http://www.amk.ca/python/code/crypto.html">PyCrypto</a></li>
  66 </ul>
  67 </li>
  68
  69 <li><h4>PyMSNt</h4>
  70 <p>
  71 Download PyMSNt from <a href="http://delx.cjb.net/pymsnt">delx.cjb.net/pymsnt</a> and decompress it to a suitable location.
  72 </p>
  73 </li>
  74
  75 <li><h4>Configure</h4>
  76 <p>
  77 Copy the file config-example.xml to config.xml and edit it to suit your environment.<br/>
  78 Note, with older versions of PyMSNt you were supposed to edit config.py. This is NOT recommended in this version.
  79 </p>
  80 <ul>
  81 <li>The 'jid' setting should be the ID you want PyMSNt to take on the network.
  82 Example: 'msn.host.com'.</li>
  83 <li>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!</li>
  84 <li>The 'mainServer' setting should be the IP address or DNS of the main Jabber server.
  85 Default: '127.0.0.1'.</li>
  86 <li>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'.</li>
  87 <li>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.</li>
  88 <li>The 'website' setting should be a website to refer users to.</li>
  89 <li>There are other options in this file that are documented by comments. It is safe to leave them at the default values.</li>
  90 <li>Ensure that the transport can make outgoing connections on port 443 (HTTPS), 1863, as well as incoming connections on 8010 (for Jabber file transfers).</li>
  91 </ul>
  92 </li>
  93
  94 <li><h4>Spool directory</h4>
  95 <p>
  96 PyMSNt stores login information (MS Passport account, password and nick) in the spool directory.
  97 This directory should meet this conditions:
  98 </p>
  99 <ul>
 100 <li>be located in the same place as the README and TODO files</li>
 101 <li>be writeable by whatever system user will be running PyMSNt</li>
 102 <li>have the same name as the 'jid' value you specified above in config.xml. (for example: 'msn.host.com')</li>
 103 </ul>
 104 <p>
 105 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.<br/>
 106 Don't forget to rename it to the 'jid' value you specified on config.xml
 107 </p>
 108 </li>
 109
 110 <li><h4>Configure Jabber server</h4>
 111 <p>
 112 Now you have to configure your Jabber server.
 113 The following section covers this in detail.
 114 </p>
 115 </li>
 116
 117 <li><h4>Start PyMSNt</h4>
 118 <p>
 119 Now you're ready to start PyMSNt for the first time:
 120 </p>
 121 <pre>
 122 ./PyMSNt.py
 123 </pre>
 124 <p>
 125 It will connect to the Jabber server and serve the Discovery JID you specified.
 126 Note: PyMSNt does not implement the old and deprecated 'Browse' capacity,
 127 only the newer 'Discovery'.
 128 </p>
 129 <p>
 130 On MS Windows you can run it by opening a DOS console in the PyMSNt directory and running "python PyMSNt.py"
 131 </p>
 132 <p>
 133 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.
 134 </p>
 135 </li>
 136
 137 </ol>
 138
 139 <hr/>
 140
 141
 142 <h3>Jabber Server Configuration</h3>
 143
 144 <p>The instructions below assume you are running PyMSNt on the same machine as your main Jabber server</p>
 145
 146 <ul>
 147 <li><h4>Jabberd1.4.x</h4>
 148 <p>If you are using Jabberd1.4.x then you need to add this to your jabber.xml file</p>
 149 <pre>
 150   &lt;service id=&quot;msn.host.com&quot;&gt;
 151           &lt;host&gt;msn.host.com&lt;/host&gt;
 152           &lt;accept&gt;
 153                   &lt;ip&gt;127.0.0.1&lt;/ip&gt;
 154                   &lt;port&gt;5347&lt;/port&gt;
 155                   &lt;secret&gt;secret&lt;/secret&gt;
 156           &lt;/accept&gt;
 157   &lt;/service&gt;
 158 </pre>
 159 <p>
 160 Check that msn.host.com is the same as the 'jid' setting from config.xml and
 161 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 &lt;ip/&gt; tag is (in this example the loopback interface is used. So 'mainServer' would be '127.0.0.1').
 162 </p>
 163 <p>You must also add this to the browse section of your jabber.xml file</p>
 164 <pre>
 165  &lt;service type=&quot;msn&quot; jid=&quot;msn.host.com&quot; name=&quot;MSN Transport&quot;&gt;
 166    &lt;ns&gt;jabber:iq:register&lt;/ns&gt;
 167    &lt;ns&gt;jabber:iq:gateway&lt;/ns&gt;
 168  &lt;/service&gt;
 169 </pre>
 170 <p>Once again, msn.host.com must correspond to the 'jid' setting in config.xml</p>
 171 <p>Once you have made all these changes, restart your Jabberd1.4.x server, then start PyMSNt and it should all work.</p>
 172 </li>
 173
 174 <li><h4>Jabberd2</h4>
 175 <p>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.</p>
 176 <p>You may need to add the following to your Jabberd2 router-users.xml</p>
 177 <pre>
 178 &lt;user&gt;
 179         &lt;name&gt;msn.host.com&lt;/name&gt;
 180         &lt;secret&gt;secret&lt;/secret&gt;
 181 &lt;/user&gt;
 182 </pre>
 183 <p>
 184 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
 185 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.
 186 </p>
 187 </li>
 188
 189 <li><h4>ejabberd</h4>
 190 <p>
 191 To configure ejabberd for PyMSNt, as explained in <a
 192 href="http://ejabberd.jabberstudio.org/guide.html#htoc17">ejabberd Guide</a>:
 193 </p>
 194 <ol>
 195 <li>Edit <i>ejabberd.cfg</i>.</li>
 196 <li>In the section that says: '<i>{listen,</i>' add those two lines:
 197 <pre>
 198     {5347, ejabberd_service, [{host, "msn.host.com",
 199                                [{password, "secret"}]}]},
 200
 201 </pre>
 202 </li>
 203 <li>Restart ejabberd and you're done.</li>
 204 </ol>
 205 </li>
 206
 207 <li><h4>Wildfire</h4>
 208 <p>
 209 In the Wildfire administration console, click the Server tab, and then External Components.
 210 Enable external components and enter a port (default is 10015) and a default shared secret.
 211 </p>
 212 <p>
 213 Use the port and secret in the PyMSNt config.xml to connect the transport to Wildfire
 214 </p>
 215 </li>
 216
 217 </ul>
 218
 219 <hr/>
 220
 221
 222 <h2>Clustering</h2>
 223
 224 <p>More to be written... For now, have a look at the compjid option.</p>
 225
 226 <hr/>
 227
 228 <h2>Tips</h2>
 229 <ul>
 230 <li>You can send 'end' to the transport's bare JID at any time to completely destroy your session.</li>
 231 <li>You can specify the transport should use a different config file by passing the name of the file as an argument, eg
 232 <pre>
 233 ./PyMSNt -c /etc/jabber/pymsnt.xml &amp;
 234 </pre>
 235 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.
 236 </li>
 237 <li>There are many settings in the config.xml file, have a look and see if any of them would be useful to you</li>
 238 <li>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 <a href="http://xmpp.org">XMPP RFCs</a>. If you want your language to be included, please have a look at lang.py, make a translation and send it to me.</li>
 239 <li>On Unix platforms sending a SIGHUP will cause the transport to reload the config file and close &amp; open the debug.log file, eg
 240 <pre>
 241 kill -1 `cat PyMSNt.pid`
 242 </pre>
 243 Run in the directory that PyMSNt.pid is in. This will send a SIGHUP signal to the transport.
 244 </li>
 245 <li>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.</li>
 246 <li>To disable file transfer, simply comment out the ftJabberPort and ftOOBPort options. This will disable file transfer in both directions.</li>
 247 <li>To keep the size of the avatar spool directory down, try adding a command like this to your cronfile: <pre>find /path/to/msn.host.com/avatars -atime +30 -delete</pre></li>
 248 <li>To get the latest version of the transport, run this command: <pre>svn co svn://delx.cjb.net/pymsnt/trunk pymsnt</pre></li>
 249 </ul>
 250 <hr/>
 251
 252 <h2>Possible problems:</h2>
 253
 254 <ul>
 255 <li>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).</li>
 256 <li>See the <a href="http://delx.cjb.net/pymsnt/docs/user.html">User's Guide to PyMSNt</a> for more details on using the transport</li>
 257 <li>Do not use Twisted 2.0.0. It is buggy!</li>
 258 <li>If you are upgrading from the CMSN-t and your Jabber server has been running
 259 prior to about November 2003 then some of your users' contact lists may have
 260 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).</li>
 261 <li>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:
 262 <pre>find -name '*.xml' -exec cp -v {} fixed_msn.host.com \;</pre>
 263 </li>
 264 </ul>
 265
 266 <hr/>
 267
 268
 269
 270 <p>Bug reports and comments go to <a href="mailto:james&#64;delx.cjb.net">James Bunton</a></p>
 271 <p>I'll gladly help you with any problems, but please look through this whole page, the README &amp; config.xml files first.</p>
 272
 273 <hr/>
 274 <p>Copyright James Bunton &lt;james at delx.cjb.net&gt;. You may freely redistribute this file.</p>
 275
 276 </body>
 277
 278
 279 </html>