Gentoo Wiki


This HOWTO explains how to install a Jabber instant-messaging server on your Gentoo machine, using the jabberd v2.x server. (There are also other servers available if jabberd2 doesn't take your fancy.)

This isn't as complicated as it looks! Working from this HOWTO you should have a basic Jabber server up and running in well under an hour (not counting compile time.)


Installing jabberd

Since jabberd2 is still in testing, it will need to be unmasked in /etc/portage/package.keywords (but this step can be skipped when v2 has been classed as stable.)

File: /etc/portage/packages.keywords
 net-im/jabberd2 ~x86   # (or ~amd64 or whatever)

Next, emerge jabberd with the required authentication modules. You will need to select which database to use - this howto covers both MySQL and PostgreSQL. Your choice will probably depend on which database you already have running on your server. Currently the MySQL procedure is easier to follow, until someone cleans up the PostgreSQL section.

Set the required USE flags (if you don't already have them in make.conf) like postgres or mysql, and ssl. SSL support is strongly recommended, as it will allow users to connect to your server over an encrypted channel.

USE="mysql ssl" emerge -av net-im/jabberd2

Remember that if you specify the flags in /etc/portage/package.use then they won't be lost if you upgrade later on.

Once the install has completed, you will need to configure the server and create a database for the server to use.


XML config files

This section will explain the common changes you will need to make to the XML configuration files, normally located in /etc/jabber(it's not jabberd, but jabber where - maybe it changed over time?). For this section you will need:

The domain part of the JID deserves special mention, as it can be tricky to get going. This name must be resolvable by DNS (so using the example domain above, you should be able to ping the machine jabberd will be running on by doing ping If this doesn't work it will cause some problems, particularly with older clients (you can fix this for newer clients by setting up SRV records in DNS, see the Jabber Admin manual at the end of this page for more info.)

By far the easiest "domain" to use is the FQDN of your machine (e.g. "") - the down side of course, is that all your users will have JIDs like which isn't quite as nice.


This is the "client to server" configuration file, which stores settings used when a Jabber client connects to your server.

Near the top of the file, change the "secret" password to something more secure. This password will be reused in all the XML files, as it is used to prevent unauthorised components from linking in with your Jabber server - so pick a decent password! There's no need to remember it once you've entered it in all the XML files.

File: /etc/jabber/c2s.xml
  <!-- Username/password to authenticate as -->
    <user>jabberd</user>                   <!-- default: jabberd -->
    <pass>dY4g59fX58vKs5Gkf9p8Vn4f</pass>  <!-- default: secret -->

Under the <local> section, you will need to set your JID domain. Take care to note that this is not the <id> tag at the top of the file in the <c2s> section - that <id> tag must always be set to "c2s".

File: /etc/jabber/c2s.xml


Only the shared password needs to be changed in this file.


Only the shared password needs to be changed in this file.


Only the shared password needs to be changed in this file.


Only the shared password needs to be changed in this file.


You will need to set your server's <id> again in this file. It must match the <id> specified in c2s.xml above.

Again, the shared password needs to be set in this file. You can also grant extra access to certain JIDs here (such as the ability to broadcast a message to all users.) It might be a good idea to put your own ID in here (or an admin ID, if you like to keep things separate.)

File: /etc/jabber/sm.xml
<!-- Access control information -->
    <!-- The JIDs listed here will get access to all restricted
         functions, regardless of restrictions further down -->
    <acl type='all'>

You will also need to configure your database in this file - see the database sections below for details.

There are other interesting options in this file (particularly if you disabled new-user registration in c2s.xml) so have a quick glance through it.

Log files

By default the Jabber server logs to syslog, if you're happy with this you can skip this section, however if you don't want your normal log files flooded with Jabber messages you will probably want everything logged to separate files.

To do this, you will need to edit all the .xml configuration files (by default stored in /etc/jabberd) and perform these changes:

After these changes, all your XML files should look similar to this example of c2s.xml:

File: /etc/jabber/c2s.xml
  <!-- Log configuration - type is "syslog", "file" or "stdout" -->
  <log type='file'>
    <!-- If logging to syslog, this is the log ident -->

    <!-- If logging to syslog, this is the log facility
         (local0 - local7)                        [default: local3] -->
    <!-- If logging to file, this is the filename of the logfile -->

Because the default log location is in /var/jabberd and most people keep their logs in /var/log, and because the ebuild creates the files in /var/jabberd with all the correct permissions, it's easier just to create a symlink to this folder in your normal log file directory:

# cd /var/log
# ln -s /var/jabberd/log jabberd

Then when you go hunting for the Jabber log files in /var/log/jabberd/, they'll be where you expect.

SSL / Encrypted connections

Adding SSL support will allow users to securely connect to your Jabber server through an encrypted connection (in the same way that HTTPS allows you to securely connect to websites.) This is of course optional, and you may wish to skip this step for the moment and return once the server is up and running with unencrypted connections.

For this to work you will either need a self-signed certificate, or preferably get a real one from somewhere like (real ones have the advantage that your users won't be prompted about potential security issues with your certificate, as they would if you used a self-signed one.) If you have HTTPS working through Apache, you can reuse the same certificates with jabberd.

All secure client settings are stored in the "client to server" configuration file (c2s.xml), so in this file:

The .pem file is simply your server certificate (as used by Apache) with your private key on the end (e.g. cat privatekey.pem >> server.pem) if you use the same hostname for both, Jabberd and Apache (eg. or If not, you can create a self signed certificate using openssl:

openssl req -new -x509 -nodes -out /etc/jabberd/server.crt -keyout /etc/jabberd/server.key

Please set CN (Common name) to the host name that your clients will use to communicate with your jabberd.

In the next step you have to copy the content of both files into the file named server.pem. (You can delete server.key and server.crt after creating server.pem.)

CAUTION: The private key is in clear text now, so you should protect adequately.

You will want to check c2s.log to make sure it is picking up your certificate and listening on port 5223.

You can also specify this pemfile in s2s.xml if you want to enable server-to-server encrypted connections (probably also a good idea.)

TODO: Put in a way to check whether server-to-server connections are actually encrypted or not

Database setup

If you have decided to use PostgreSQL as the underlying storage mechanism for your Jabber server, see the PostgreSQL section below. If you've decided to use MySQL instead, skip down to the MySQL section.

Using PostgreSQL

Now, we create a postgres user and database for jabberd.

We create it as the postgres user, the username is jabberd2 disable pretty much everything and ask for a password

-S, --no-superuser        role will not be superuser
-D, --no-createdb         role cannot create databases
-R, --no-createrole       role cannot create roles

Note: Since postgresql 8.x there doesn't seem to be a 'user' nor is it called 'is allowed to create users' but they changed it to 'rules'. Oh well.

createuser -U postgres jabberd2 -S -D -R -P 
Enter password for new role: 
Enter it again: 

Note: Personally, I prefer getting a password from or the like, just make sure you write it down (it will be saved in your xml files later.

Next create the database for jabberd and let it be owned by jabberd.

createdb -U postgres -E UNICODE jabberd2 -O jabberd2

Prepare the db-setup.psql file and test/import our db. Next we test our db and import the jabberd template.

(replace jabberd-2.0.11 with your version of jabberd obviously, ignore the error/warning about unable to create the db, we just did that.)

zcat /usr/share/doc/jabberd-2.0.11/tools/db-setup.pgsql.gz | psql -U jabberd2 jabberd2

Next, open /etc/jabberd/sm.xml and setup the 'driver' section under 'storage' (The ebuild could have changed that for us when only using the postgres flag, oh well)

...scroll down to <pgsql> section ...
the only thing that you should change is the password.

Personally, i'd like to use my mail db that I allready have a db for and offer jabber to my mail users. One option would be to (finally) change to ldap for everything, until that is possible, we'll just the pgsql backend and duplicate users or something.

In c2s.xml under the section 'authreg' we set <module>pgsql</module> and again, set the password in the <pgsql> section as we did earlier.

Time to test the server!

(Now for me, it failed [!!] the first time, so into syslog we go to find out what's going on. If your lucky and it just works the first go, lucky you!, according to it's not just me ...) The 'hack' worked, but it's ugly.

For additional setup, i'd go read the docs : ) (or wait for me to get off my lazy bum and setup/document more)

Using MySQL

Create the database

Create the jabberd2 database

You will need to connect to the MySQL database as a user with enough access to create the database. If you already have a database you will be using, and a username and password to access it, you can skip this step.

# mysql -u root -p
mysql> CREATE DATABASE jabberd2;
mysql> GRANT ALL ON jabberd2.* TO jabberd2@localhost IDENTIFIED BY 'secret';

The database name, username and password must match what is entered into the jabberd configuration files below.

Create the tables

The jabberd ebuild contains the database schema which will create the tables in the database. The path to db-setup.mysql.gz may need to be changed depending on the version of jabberd installed.

# bzcat /usr/share/doc/jabberd-2.1.6/tools/db-setup.mysql.bz2 | mysql -f -p -u jabberd2 jabberd2
ERROR 1007 (HY000) at line 8: Can't create database 'jabberd2'; database exists

The error about the database already existing is fine, we just created it above. The -f option tells mysql to keep running the script after the error and create the tables anyway. If you are using a different database or username, adjust the mysql command accordingly (the -u jabberd2 supplies the username and the second jabberd2 is the database name. The command will prompt for a password.)

Configure jabberd


In the <authreg> section, set the <module> to mysql.

File: /etc/jabber/c2s.xml
  <!-- Authentication/registration database configuration -->
  <!-- Backend module to use -->

In the <mysql> section, enter your database information.

File: /etc/jabber/c2s.xml
  <!-- MySQL module configuration -->
    <!-- Database server host and port -->

    <!-- Database name -->

    <!-- Database username and password -->


In the <storage> section, set the <driver> to mysql.

File: /etc/jabber/sm.xml
 <!-- Storage database configuration -->
    <!-- By default, we use the MySQL driver for all storage -->

Then just below that, enter the database information.

File: /etc/jabber/sm.xml
    <!-- MySQL driver configuration -->
      <!-- Database server host and port -->

      <!-- Database name -->

      <!-- Database username and password -->

      <!-- Transacation support. If this is commented out, transactions
           will be disabled. This might make database accesses faster,
           but data may be lost if jabberd crashes.
           This will need to be disabled if you are using a MySQL
           earlier than v3.23.xx, as transaction support did not appear
           until this version. -->

The database configuration is now complete!

Running the server

At this point your Jabber server should be ready to go! Now is a good time to add it to your startup scripts:

rc-update add jabberd default

Then start it in the normal way:

/etc/init.d/jabberd start

And after a couple of seconds, check the logs to make sure everything came up successfully:

# tail /var/log/jabber/sm.log
Sun Sep 24 12:31:26 2006 [notice] initialised storage driver 'mysql'
Sun Sep 24 12:31:26 2006 [notice] version: jabberd sm 2.0s11
Sun Sep 24 12:31:26 2006 [notice] attempting connection to router at, port=5347
Sun Sep 24 12:31:26 2006 [notice] connection to router established
Sun Sep 24 12:31:26 2006 [notice] ready for sessions

If there are any errors, check the troubleshooting section below, otherwise your server is now up and running!


It is possible to configure your Jabber server to connect to other instant-messaging networks, such as ICQ and MSN. If you are not interested in your Jabber users being able to connect to other IM networks through your server, you can skip this section. Your Jabber server should be working correctly on the Jabber network before you start following the instructions in this section - if it's not, you'll run into many obscure problems.


This section explains how to set up an ICQ transport so that users on your Jabber server can add people on the ICQ network to their Jabber contact list. Once this is working correctly, ICQ contacts will appear alongside Jabber contacts, using any standard Jabber client (even one that knows nothing about the ICQ network.)


You will need to install the JIT package (Jabber ICQ Transport) in order to connect to the ICQ network through the Jabber server.

# emerge -av net-im/jit

NOTE: It is also possible to use a python-based daemon instead: emerge -av net-im/pyicq-t ... a similar transport for MSN is also available, emerge -av net-im/pymsn-t ... a yahoo transport is available but not yet in portage, see bug #142041.

JIT Configuration

Note: At the time of writing, the net-im/jit-transport ebuild does NOT include the xdb_file library. This means that you will be unable to use JIT with jabberd 2.x, unless you compile xdb_file from source yourself. If xdb_file is ever included in the ebuild, the instructions in this box will become unneccessary.

See bug 148920 for progress.

To install xdb_file, you will need to download the JIT sourcecode from the JIT homepage and compile the xdb_file library:

 # tar zxvf jit-1.1.4.tar.gz
 # cd jit-1.1.4
 # ./configure
 # cd xdb_file
 # make
 # su -c 'cp /usr/local/lib'
 # ldconfig
You should now have the xdb_file library ready to go, and you can continue with the rest of the instructions in this section.

The JIT configuration is stored in /etc/jabber/jit.xml (note there's no 'd' on the end of /etc/jabber.) The first part of this file to modify is the logging section at the top. Apparently JIT is supposed to send log messages to jabberd, but this doesn't seem to work with jabberd v2.x so the only way of seeing the log messages is by getting JIT to log to a file directly. This can be done by uncommenting the <log> sections and putting the log files in with the rest of the Jabber logs (which will be available in /var/log/jabberd/ if you followed the logfile configuration above.)

File: /etc/jabber/jit.xml
 <log id='elogger'>
    <format>%d: [%t] (%h): %s</format>

  <log id='rlogger'>
    <format>%d %h %s</format>

Note that this will produce a new log file every day, so someone really should figure out a cleaner way of doing this logging.

Since we're using jabberd v2.x which doesn't provide XDB services, uncomment the <xdb> section in jit.xml, enter the path to the library and supply a valid "spool" path for storing userdata (we'll use /var/spool/jabber, which we'll create in a moment.)

File: /etc/jabber/jit.xml
  <xdb id="xdb">
    <xdb_file xmlns="jabber:config:xdb_file">
      <spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>

Now make sure the spool directory exists and is writable by the jabber user:

 # mkdir /var/spool/jabber
 # chown jabber:jabber /var/spool/jabber

Next, put the correct hostnames in the JIT config file. These have to be different from your other domain names, and they must be resolvable via DNS. This example assumes your server sits at "" and your JIDs are of the form We will also set the <status> to away as this will make any SMS contacts on your Jabber list appear as though they're in "away" mode (as opposed to the default of offline, which can be misleading.)

File: /etc/jabber/jit.xml
 <service id="">

    <!-- to enable sms. Replace localhost with the same name as above -->
    <!-- JIT configuration -->
    <icqtrans xmlns="jabber:config:icqtrans">

If JIT is running on the same machine as jabberd, your hostnames might look like this:

# host has address

# host is an alias for has address

# host is an alias for has address

Of course I have used aliases (CNAMEs) to keep the work down if I ever have to change IP addresses, you could easily have used A records to supply the same IP address to all three hostnames.

Towards the end of jit.xml, you will need to supply JIT with the password used to connect to the router, as well as the correct port that the router is listening on (you will probably need to change this to jabberd2's default of 5347, not JIT's default 5555):

  <service id="icqlinker">

Now edit jabberd2's router.xml and in the <aliases> section, tell it to forward any packets destined for these hostnames to JIT:

File: /etc/jabberd/router.xml
    <!-- Example for a MUC component running from a jabberd 1.4 uplink -->
    <alias name='' target='muclinker'/>
    <alias name='' target='icqlinker'/>
    <alias name='' target='icqlinker'/>

Then edit sm.xml and in the <items> section, list JIT as an available service on your server:

File: /etc/jabberd/sm.xml
      <item category='gateway' type='icq' jid='' name='ICQ Gateway (offline)'>

      <item category='gateway' type='sms' jid='' name='ICQ SMS Gateway (offline)'>

The 'name' field is what will appear before JIT connects, so by putting "offline" in there it makes it a bit more obvious if JIT hasn't connected or has crashed - once JIT successfully connects it overrides that text.

Lastly, don't forget to load JIT at startup:

rc-update add jit-transport default

Once your Jabber server is up and running, load JIT in the normal way:

/etc/init.d/jit-transport start

If you have troubles, you can tell JIT not to daemonise and log to the console, to find out what's going on:

/usr/sbin/jit-wpjabber -c /etc/jabber/jit.xml -H /var/spool/jabber -D

Running JIT

Make sure jabberd is running first. Remember to restart it if necessary, now that the config files have been changed.

/etc/init.d/jabber stop
<wait for a second or two
/etc/init.d/jabber start

It is necessary to wait for a while before restarting jabberd, running /etc/init.d/jabber restart doesn't give it enough time and often the server won't restart giving you messages about being unable to kill certain PIDs (and then you'll need to run /etc/init.d/jabber zip before you can start it again.)

The first time you run JIT, you will probably want to do so in debug mode as there are no failure messages otherwise if it doesn't work. This command is taken from /etc/init.d/jit-transport, with "-d" removed (so that it doesn't daemonise.)

/usr/sbin/jit-wpjabber -c /etc/jabber/jit.xml -H /var/spool/jabber

TODO: This fails saying can't be found, figure out how to install xdb.

If no errors are printed, check the router.log and see if the icqlinker service connected:

# tail /var/log/jabberd/router.log
Sun Sep 24 17:52:55 2006 [notice] [, port=48510] connect
Sun Sep 24 17:52:55 2006 [notice] [, port=48510] authenticated as icqlinker
Sun Sep 24 17:52:55 2006 [notice] [icqlinker] online (bound to, port 48510)
Sun Sep 24 17:52:55 2006 [notice] [] online (alias of 'icqlinker', bound to, port 48510)
Sun Sep 24 17:52:55 2006 [notice] [] online (alias of 'icqlinker', bound to, port 48510)

If all is well, you can stop the debug version of JIT (Ctrl+C) and then start things properly.

/etc/init.d/jit-transport start

You should now have the ICQ service available on your Jabber server. Adding ICQ contacts to your Jabber roster varies between clients, so check the instructions for your Jabber client. If you're using Psi, you can do this through the Service Discovery - right-click on the JIT service and register with it first (this is where you supply your ICQ UIN and password) and from then on when you add a contact to your list you'll have the option to select the ICQ network.


Server fails to start

Check the logs

If your server fails to start, check the log files in /var/log/jabberd (assuming you followed the log files section above.) One of these files will normally tell you why the server stopped running. Most of the files will say that the component exited because one of the others quit, so you will have to follow the trail until you find which component was the one that initiated the shutdown.

Can't connect to server

Check <id> tags

The trickiest problem when setting up a new Jabber server is getting the <id> tag correct. If it's even slightly off, the server may not start, or it will start but you'll be unable to connect to it. Make sure you've used your FQDN and bare domain in the correct places. Namely c2s.xml and sm.xml!

Check SSL settings

If you're trying to connect via SSL, make sure the server has enabled SSL. If the certificates are in an invalid format, a warning will be printed in the logs and the server will ignore any SSL connections.

File: /var/log/jabberd/c2s.log
Tue Sep 26 21:54:50 2006 [error] failed to load local SSL pemfile, SSL will not be available to clients

More information

Retrieved from ""

Last modified: Thu, 18 Sep 2008 05:47:00 +0000 Hits: 16,635