- [ docs.jabber.org ]

Jabber Server 1.4 HOWTO

Introduction
System Requirements
Server Installation
Server Configuration
Adding Services

Adding Conferencing
Adding JUD
Adding the AIM Transport
Adding the ICQ Transport
Adding the MSN Transport
Adding the Yahoo Transport

Running Services in Separate Processes
Upgrading from Earlier Versions
Getting Assistance
Providing Feedback
Acknowledgements
References
Copyright Information

Introduction

Jabber is an XML-based, client-server, open-source presence and messaging system that uses a network of distributed servers to pass data between servers and ultimately to Jabber clients. This document provides information about installation and configuration of version 1.4 of the Jabber server. If you have been running a 1.0 or 1.2 server, now is the time to upgrade, because the 1.4 codebase is superior to earlier versions and future development regarding transports and other add-ons will focus on compatibility with the 1.4 server. For detailed technical information about Jabber, please see the References section of this document. This document received its last major update on 2001-02-07. Since that time, additional information about the 1.4 server has been added to the Jabber FAQ, so check there if you're stuck on a problem. On 2001-09-08, updated information about installing the AIM and ICQ Transports was added.

System Requirements

The Jabber server 1.4 was developed mainly on Linux, with additional testing on FreeBSD and Solaris. It has been successfully built on AIX, IRIX, and several other flavors of Unix. Hardware requirements for installation are minimal: the server has been installed and run on early Pentiums. A typical install for an intranet or small website might be a Pentium workstation with 256 or 512 megs of RAM running Linux. Note that if you are running Linux, you will need to modify some settings in the /proc filesystem to make it support more than 1024 simultaneous connections (consult your Linux documentation for how to do this).

Server Installation

The 1.4 server can be downloaded at http://download.jabber.org/dists/1.4/final/. This includes all the core code for messaging and presence within Jabber. Additional components, such as conferencing (a.k.a. groupchat), the Jabber User Directory, and transports to other IM services, are contained in the same directory and will be covered later in this document.

The build process for the Jabber server just keeps getting easier, thanks to the hard work of the core team and contributions from the volunteers who have tested the installation process on Solaris, AIX, Tru64, and so on. The only file you need to download and install is jabber-1.4.tar.gz, available at http://download.jabber.org/dists/1.4/final/. To install it, do the following:

save the file to /tmp/ (or your directory of choice)
open a console window and create the directory where you would like to install your Jabber server -- I'll refer to this as /path/to/jabber/, but an example might be /usr/local/jabber/ (note that you might need to log in as root or use sudo to do this)
mv /tmp/jabber-1.4.tar.gz /path/to/jabber/
cd /path/to/jabber/
gzip -d jabber-1.4.tar.gz
tar -xvf jabber-1.4.tar (this creates a jabber-1.4/ directory containing various files and subdirectories)
cd jabber-1.4/
./configure
make

Note: if you are running Solaris or some other non-GNU system, be sure to use GNU make, not your native version of make. You will probably also need to install GNU pth as well. And if you are running Red Hat 7, do yourself a favor and install the crucial update related to problems with "gcc 2.96".

Server Configuration

The core Jabber server should now be installed on your system. The next step is to configure the server so that you can run it. Most of the configuration happens in a file named jabber.xml, which contains a lot of comments that help you understand what each configuration option does. Since things are explained quite well in jabber.xml, the only changes we'll make here are the ones you need in order to get the server running. So open jabber.xml in your favorite text editor and do the following:

In the line reading

<host><jabberd:cmdline flag="h">localhost</jabberd:cmdline></host>

change 'localhost' to the name of your host machine. Obviously you don't need to do this if you are just playing with the server on your local machine. However, if you want to be able to communicate with other Jabbers servers running version 1.4, you will need to make sure that the <host/> is a fully qualified domain name! This is also true of all subdomains you add (for services such as conferencing, JUD, and the transports), so you may need to have your local system administrator add your hostname and all relevant to the DNS tables for your domain. Also, if you don't want to run the server with the -h flag, you can remove the jabberd:cmdline element and simply have <host>yourdomainname</host>
Comment out the line that reads

<update><jabberd:cmdline flag="h">localhost</jabberd:cmdline></update>

(or if you keep it, change 'localhost' to the name of your host machine).
Optionally, adjust the <welcome/> text and change the <admin/> entries.

Because the Jabber server stores user "rosters" on the filesystem (specifically, in a subdirectory of the jabber-1.4/spool/ directory), you need to create a writable subdirectory of spool/ that has the same name as your hostname. So if the hostname of your Jabber server is jabber.foobar.com, you will need to create a directory jabber-1.4/spool/jabber.foobar.com/ that is writable by the user who runs the server.

So who is this "user who runs the server"? Well, ideally it's you. But certainly it's not root! As I'm sure you know, it's a security hazard to run any major piece of software (including the Jabber server) as root! You can change the ownership rights to the entire Jabber server directory by typing, as root, something like chown -R myusername.myusergroup /path/to/jabber/.

OK, now that you're practicing safe computing, you can fire up the Jabber server:

To run the server, type ./jabberd/jabberd -h yourhostname
To run the server in debug mode, type ./jabberd/jabberd -D -h yourhostname
To monitor server activity, type tail -f error.log

The Jabber server should now be running on your machine. You can now connect to the server using your favorite Jabber client (see http://www.jabbercentral.com/clients/ for a list).

Adding Services

Well, Jabber is pretty cool all by itself, but one of the main reasons people are interested in Jabber, and the 1.4 server in particular, is the fact that Jabber has additional services such as the "transports" that enable Jabber users to exchange messages and presence with users of other instant messaging services. In addition to conferencing (a.k.a. groupchat) and the Jabber User Directory (JUD), the four transports that currently exist in the Jabber world connect to AOL Instant Messenger (AIM), ICQ, MSN Messenger Service (MSN), and Yahoo! Messenger (Yahoo). We'll cover conferencing and JUD first, then delve into the transports.

Note #1: Just as with your base hostname, in order to get these services to work you need to make sure that each relevant subdomain (e.g., aim.yourdomain.com) is a fully qualified domain name!

Note #2: For each component discussed below, the first <service/> section related to the component must be included in the <browse/> section of your jabber.xml -- this <service/> element identifies the component as something that a user can browse to and interact with (e.g., by registering with it). The actual definition of this component, where you point to a .so file or link off to a separate XML config file, must not go inside the <browse/> section -- usually I recommend that you put the service definitions right before the closing </jabber> tag at the end of the file just to make sure that they are not within the <browse/> element. If you are confused about this, please refer to the XML configuration file examples I have posted at http://www.saint-andre.com/jabber/xml/.

Adding Conferencing

The conferencing module has been rewritten specifically to work with the 1.4 server, so forget everything you ever knew about groupchat! (D.J. Adams has written a helpful groupchat roundup to help you sort things out.)

First, note that if you want your conference rooms to be accessible to users of other Jabber servers, the sub-domain conference.your.domain.name must be resolvable to a DNS address (probably to the same IP as your.domain.name). You may need to have your local DNS tables updated with this information. If you're using a dynamic DNS service like dyndns.org, make sure you enable the wildcard option so that subdomains will be resolved.

The new conferencing code is available at http://download.jabber.org/dists/1.4/final/. As of this writing, the current version is 0.4, so download conference-0.4.tar.gz to your jabber-1.4/ directory. Then do the following:

gzip -d conference-0.4.tar.gz
tar -xvf conference-0.4.tar (this will create a conference-0.4/ sub-directory)
cd conference-0.4/
make (for non-GNU systems, see note above about using gmake)

The conferencing code should now be installed on your system (you'll know if that's the case if you see a conference.so file in the conference-0.4/ directory). The next step is to configure your Jabber server to run conferencing, so open jabber.xml and make the following edits...

First, in what will become a familiar pattern as you add services on top of your core server, you need to identify the conferencing service in the <browse/> section of jabber.xml so that users of your server can discover that you offer conferencing. You do this by adding the following line to the <browse/> section of your jabber.xml file:

<conference type="private" jid="conference.localhost" name="Conferencing"/>

Of course, you'll need to replace 'localhost' with the hostname of your Jabber server.

Next, you need to actually define the service you're offering by adding a <service/> element to jabber.xml (I usually put it right after the <service/> definition for the s2s component).

<service id="conference.localhost">
<load><conference>./conference-0.4/conference.so</conference></load>
<conference xmlns="jabber:config:conference">
<vCard>
<FN>Conferencing Service</FN>
<DESC>This service is for private chatrooms.</DESC>
<URL>http://localhost/</URL>
</vCard>
<history>20</history>
<notice>
<join> has joined</join>
<leave> has left</leave>
<rename> is now known as </rename>
</notice>
</conference>
</service>

Here again you'll need to replace 'localhost' with the hostname of your Jabber server.

OK, now you're ready to restart the Jabber server and take conferencing for a spin! You should see "Conferencing" as a service on the server when you connect with a Jabber client. You should also be able to type a conference room name into the interface for joining a conference room and then join that room. Invite a friend or two into a conference room and jabber away!

Adding JUD

JUD stands for Jabber User Directory. The main instance of JUD lives at jabber.org, and anyone can add their name to the user database there so that people can find them (note that JUD is an opt-in database, user information is never added to JUD automatically on registration). In addition to the JUD instance at jabber.org (or to supersede it), you can define a JUD instance that lives on your Jabber server so that your users can register with a directory on your server. To do that, you can use the re-written JUD code that is available at http://download.jabber.org/dists/1.4/final/. Here's how:

gzip -d jud-0.4.tar.gz
tar -xvf jud-0.4.tar (this will create a jud-0.4/ sub-directory)
cd jud-0.4/
make (for non-GNU systems, see note above about using gmake)

The JUD code should now be installed on your system (you'll know if that's the case if you see a jud.so file in the jud-0.4/ directory). The next step is to configure your Jabber server to run JUD, so open jabber.xml and make the following edits...

As we saw with conferencing, first you need to identify the Jabber User Directory in the <browse/> section of jabber.xml so that users of your server can discover that you have an instance of JUD on your server (of course replacing 'localhost' with the hostname of your Jabber server as you go along). You do this by adding the following line to the <browse/> section of your jabber.xml file:

<service type="jud" jid="jud.localhost" name="localhost User Directory">
<ns>jabber:iq:search</ns>
<ns>jabber:iq:register</ns>
</service>

Here again, you need to actually define the service you're offering by adding a <service/> element to jabber.xml (a good place for this would be right after the <service/> definition for conferencing that we added above).

<service id="jud"> <host>jud.localhost</host>
<load><jud>./jud-0.4/jud.so</jud></load>
<jud xmlns="jabber:config:jud">
<vCard>
<FN>User Directory on localhost</FN>
<DESC>This service provides a simple user directory service.</DESC>
<URL>http://localhost/</URL>
</vCard>
</jud>
</service>

Restart your Jabber server and give JUD a try by adding your own user information to your JUD instance.

Adding the AIM Transport

The following instructions will not yield a working AIM Transport, because since the time this HOWTO was written, AOL made serious protocol changes in order to block Jabber servers from connecting to the AIM network. I will endeavor to update these instructions as soon as possible.

Although aim-transport-0.9.0 was released at the same time as the 1.4 server, developer Thomas Muldowney has since released aim-transport-0.9.5, which fixes a number of bugs in 0.9.0. So the code you want to download and install is located at http://download.jabber.org/dists/transports/aim-transport/. Download aim-transport-0.9.5.tar.gz to your jabber-1.4/ directory and then do the following:

gzip -d aim-transport-0.9.5.tar.gz
tar -xvf aim-transport-0.9.5.tar (this will create a aim-transport-0.9.5/ sub-directory)
cd aim-transport-0.9.5/
./configure --with-jabberd=/full/path/to/your/jabberd/directory (while the --with-jabberd option may not be necessary, I find it helps with compilation)
if you did not previously have pth installed, edit the Makefile so that the JABBERD_INC entry includes the full path to your installation of pth-1.3.7 in addition to the full path to the jabberd/ directory; mine looks like this:

JABBERD_INC = -I/usr/local/jabber/jabber-1.4/jabberd -I/usr/local/jabber/jabber-1.4/jabberd/pth-1.3.7
make (for non-GNU systems, see note above about using gmake)

The AIM Transport code should now be installed on your system (you'll know if that's the case if you see a aimtrans.so file in the aim-transport-0.9.5/ directory). The next step is to configure your Jabber server to run the AIM Transport, so it's time for more surgery on jabber.xml...

Once again, first you need to identify the AIM Transport in the <browse/> section of jabber.xml so that users of your server can discover that you have the AIM Transport installed on your server (of course replacing 'localhost' with the hostname of your Jabber server as you go along). You do this by adding the following line to the <browse/> section of your jabber.xml file:

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

<service id='aim.localhost'>
<aimtrans xmlns='jabber:config:aimtrans'>
<vCard>
<FN>AIM Transport</FN>
<DESC>An AIM Transport!</DESC>
<URL>http://localhost/</URL>
</vCard>
</aimtrans>
<load>
<aim_transport>./aim-transport-0.9.5/src/aimtrans.so</aim_transport>
</load>
</service>

Restart your Jabber server and register with the AIM transport to test it out.

Adding the ICQ Transport

From http://download.jabber.org/cvs/, download icq-transport.tgz (this is actually 0.9.1, which contains improvements over 0.9 -- the latter no longer works with the ICQ network because of protocol changes by ICQ) to your jabber-1.4/ directory and then do the following:

gzip -d icq-transport.tgz
tar -xvf icq-transport.tar (this will create an icq-transport/ sub-directory)
cd icq-transport/
make (for non-GNU systems, see note above about using gmake)

The ICQ Transport code should now be installed on your system (you'll know if that's the case if you see a icqtrans.so file in the icq-transport/ directory). The next step is to configure your Jabber server to run the ICQ Transport, so open jabber.xml once again...

First let's identify the ICQ Transport in the <browse/> section of jabber.xml so that users of your server can discover that you have the ICQ Transport installed on your server (of course replacing 'localhost' with the hostname of your Jabber server as you go along). You do this by adding the following line to the <browse/> section of your jabber.xml file:

<service type="icq" jid="icq.localhost" name="ICQ Transport">
<ns>jabber:iq:gateway</ns>
<ns>jabber:iq:register</ns>
<ns>jabber:iq:search</ns>
</service>

Note: Including the jabber:iq:search line above caused me to get a 405 Not Allowed error when I tried to register with the ICQ Transport, so you may not want to include it. However, this was platform-specific: including search worked on Red Hat 7 for me, but not on Debian.

<service id="icq.localhost">
<icqtrans xmlns="jabber:config:icqtrans">
<instructions>Please enter your ICQ number (in the "username" field),
nickname, and password. Leave the "username" field blank
to create a new ICQ number.</instructions>
<search>Search for ICQ users</search>
<vCard>
<FN>ICQ Transport</FN>
<DESC>This is the ICQ Transport</DESC>
<URL>http://localhost/</URL>
</vCard>
<prime>37</prime>
<ports>
<min>2000</min>
<max>3000</max>
</ports>
</icqtrans>
<load>
<icqtrans>./icq-transport/icqtrans.so</icqtrans>
</load>
</service>

Note: If you deleted the jabber:iq:search line in your <browse/> section, make sure you delete the <search/> line above. Also, note that there is a typo in the README, it has </port> instead of </ports>!

Also, if you are using the ICQ Transport behind a firewall and are experiencing problems with delivery of messages to users within the firewall, you may want to add a <disable-tcp/> tag right after the <prime/> entry, as explained in a JADMIN post from ICQ Transport developer Schuyler Heath.

Restart your Jabber server and register with the ICQ transport to test it out. And if you expect to have many people using the ICQ Transport on your Jabber server, make sure you change the <prime/> entry to some number higher than 37!

Adding the MSN Transport

From http://download.jabber.org/dists/1.4/final/, download msn-transport-1.1.tar.gz to your jabber-1.4/ directory and then do the following:

gzip -d msn-transport-1.1.tar.gz
tar -xvf msn-transport-1.1.tar (this will create a msn-transport-1.1/ sub-directory)
cd msn-transport-1.1/
make (for non-GNU systems, see note above about using gmake)

The MSN Transport code should now be installed on your system (you'll know if that's the case if you see a msntrans.so file in the msn-transport-1.1/ directory). The next step is to configure your Jabber server to run the MSN Transport, so open jabber.xml once again...

First let's identify the MSN Transport in the <browse/> section of jabber.xml so that users of your server can discover that you have the MSN Transport installed on your server (of course replacing 'localhost' with the hostname of your Jabber server as you go along). You do this by adding the following line to the <browse/> section of your jabber.xml file:

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

<service id="msn.localhost">
<msntrans xmlns="jabber:config:msntrans">
<instructions>Enter your MSN Messenger account and password. Example: user1@hotmail.com. Nickname is optional.</instructions>
<vCard>
<FN>MSN Transport</FN>
<DESC>This is the MSN Transport</DESC>
<URL>http://localhost/</URL>
</vCard>
</msntrans>
<load>
<msntrans>./msn-transport-1.1/msntrans.so</msntrans>
</load>
</service>

Restart your Jabber server and register with the MSN transport to test it out.

Adding the Yahoo Transport

From http://download.jabber.org/dists/1.4/final/, download yahoo-transport-0.8-1.4.tar.gz to your jabber-1.4/ directory and then do the following:

gzip -d yahoo-transport-0.8-1.4.linux.tar.gz
tar -xvf yahoo-transport-0.8-1.4.linux.tar (this will create a yahoo-transport-0.8-1.4/ sub-directory)
cd yahoo-transport-0.8-1.4/
./configure --with-jabberd=/full/path/to/jabber1.4/ (this seems to work on Red Hat and FreeBSD, but not Debian)
make (for non-GNU systems, see note above about using gmake)

The above instructions worked fine for me on RedHat. However, in order to get Yahoo Transport to compile on Debian, I needed to edit jabberd/jabberd.h so that the include statement for pth.h explicitly pointed to pth-1.3.7/pth.h, as so:

#include "pth-1.3.7/pth.h"

I've heard that the Yahoo Transport is difficult to build on Solaris. For Solaris 8 on Intel you might need to add -fPIC to the CFLAGS variable in the Makefile for yahootrans.a and then do 'make'. For Solaris 2.6, 2.7, and 8 on Sparc, you might want to try a pre-built binary I've placed on my website at http://www.saint-andre.com/jabber/yahoo_sol6.tar.gz.

The Yahoo Transport code should now be installed on your system (you'll know if that's the case if you see a yahootrans.so file in the yahoo-transport-0.8-1.4/src/ directory). The next step is to configure your Jabber server to run the Yahoo Transport, so open jabber.xml once again...

First let's identify the Yahoo Transport in the <browse/> section of jabber.xml so that users of your server can discover that you have the Yahoo Transport installed on your server (of course replacing 'localhost' with the hostname of your Jabber server as you go along). You do this by adding the following line to the <browse/> section of your jabber.xml file:

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

<service id="yahoo.localhost">
<load>
<yahoo_transport>./yahoo-transport-0.8-1.4/src/yahootrans.so</yahoo_transport>
</load>
</service>

Finally, note that in order for the Yahoo transport to work, you will need to make sure that you can connect to the following hosts from your server:

cs.yahoo.com:5050
msg.edit.yahoo.com:80

Restart your Jabber server and register with the Yahoo transport to test it out.

Running Services in Separate Processes

The foregoing discussion assumed that you wanted to run conferencing, JUD, and the transports in the same jabberd process as the main server. While that will get you up and running quickly, you might need a more scalable solution or just want to isolate these services from your core server (e.g., enabling you to stop and start services without stopping the core server). Jabber 1.4 makes this fairly easy by enabling you to run each service in its own process.

I'll be adding more to this section soon, but for now you might want to look at the XML config files that I'm using on my private Jabber server at jabber.to. I've put these files on the web at http://www.saint-andre.com/jabber/xml/ for your reading pleasure. To run these processes, I first start the main jabberd by typing ./jabberd/jabberd -c multiple.xml and then start up each of the child processes by typing ./jabberd/jabberd -c aimtrans.xml and such.

More detailed information to follow!

Upgrading from Earlier Versions

Now is the time to upgrade, because the 1.4 is the best Jabber server so far and will be the focus of future development. To upgrade from a 1.0 or 1.2 server, you'll probably want to do the following:

Create a tarball of user rosters from your old spool/yourhostname/ directory.
Archive your old 1.0 or 1.2 files just you have them to fall back on if needed.
Install the 1.4 server.
Move the roster tarball to your jabber-1.4/spool/yourhostname/ directory and untar it.

That's it!

Getting Assistance

For help with installation and configuration issues, try the following:

Join the Jabber discussion in the jdev conference room, located at jdev@conference.jabber.org (see the jdev page on dev.jabber.org for further information).
Send a message to the JADMIN mailing list for Jabber server administrators. To sign up for the list, visit http://mailman.jabber.org/listinfo/jadmin/.

If you cannot get answers to your questions on jdev or the JADMIN mailing list, feel free to contact the author of this document via email or Jabber at stpeter@jabber.org.

Providing Feedback

If you find bugs in the Jabber server, please send an email with detailed information about your platform and the behavior of the server to bugs@jabber.com. For more general feedback about Jabber, an email to the JDEV list for Jabber developers (http://mailman.jabber.org/listinfo/jdev/) is probably the best way to proceed.

Acknowledgements

Thanks above all to the Jabber developers who created the code you're running, especially to the following 1.4 heroes:

Jeremie Miller (jer) -- for coding up new versions of conferencing and JUD late in the game, not to mention his usual hijinks :)
Thomas Muldowney (temas) -- for his hard work on the AIM Transport, the 1.4 build system, and other assorted nightmares
Schuyler Heath (sheath) -- for adding the ICQ Transport to a plate that also includes the MSN Transport
Keith Minkler (tsbandit) -- for bringing the Yahoo Transport up to speed with the 1.4 protocol and the soon-to-be-released new version of the IRC Transport

Thanks also to the members of the Jabber mailing lists for their answers to questions posted and for putting the answers to the test on computers across the globe.

References

You may find the following references helpful:

Copyright Information

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting http://www.fsf.org/ or by writing to:

The Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307
USA


© Copyright 2000 Jabber.org - All Rights Reserved	Legal Notices / Credits / Contact Us