InstallGuide/QuickStartGuide

Go up: WikiStart

Quick Start Guide

This guide is intended to get Jabberd 2 installed and running as quickly as possible:

  1. Install OpenSSL
  2. Install SQLite
  3. Install Libidn
  4. Create Jabber User and Group
  5. Create Directories for Data and Logging
  6. Install Jabberd 2
  7. Configure Server
  8. Create Database
  9. Test Server

Jabberd 2 can use MySQL, PostgreSQL, SQLite or Berkeley DB to store its data. PostgreSQL is the recommended database for Jabberd 2; however, this guide suggests using SQLite because it requires the least amount of configuration for Jabberd 2 data storage. See the Jabberd 2 Installation and Administrative Guide for a detailed guide to installing and configuring Jabberd 2.

A.1.1. Install OpenSSL

Jabberd 2 requires that OpenSSL (version 0.9.6b or higher) be installed prior to installing Jabberd 2. If OpenSSL version 0.9.6b is not installed on your system, see the OpenSSL site or Installing OpenSSL for Jabberd.

A.1.2. Install SQLite

Jabberd 2 requires SQLite version 3.4 or higher; if this is not installed on your system, see the SQLite site or Installing SQLite for Jabberd 2.

Consideration should be exercised when choosing a data store for a Jabberd 2 production server because converting from one database to another may be difficult.

A.1.3. Install Libidn

Jabberd 2 requires Libidn version 0.3.0 or higher; if this is not installed on your system, see the GNU Libidn site or Installing Libidn for Jabberd 2.

A.1.4. Create Jabber User and Group

You should create a specific jabber user and group to run the server: 

      su
      groupadd jabber
      useradd -g jabber jabber

Note that the above commands are intended as an example. The commands and parameters for adding a user and group may vary for your system. Consult your manuals if you have any doubt about these commands.

A.1.5. Create Directories Data, Logging and PID's

You should create directories for data, logging and PID's, and your jabber user will need read and write permissions on these directories.

A.1.5.1. Create Data Directory

Create a directory to store the Jabberd database files (as superuser): 

         mkdir -p /usr/local/var/jabberd/db

A.1.5.2. Create Log Directory

Create a directory to store Jabberd log files (as superuser): 

        mkdir -p /usr/local/var/jabberd/log

A.1.5.3 Create PID Directory

Create a directory to store Jabberd PID files (as superuser): 

        mkdir -p /usr/local/var/jabberd/pid

A.1.5.4. Set Ownership for Data and Log Directories

Change the ownership of the directories created above (as superuser). If you used the locations specified above, enter the command: 

        chown -R jabber:jabber /usr/local/var/jabberd

A.1.6. Install Jabberd 2

This section describes how to download, configure, build and install Jabberd 2 on your system.

A.1.6.1. Download Jabberd

Download the file jabberd-2.1.n.tar.gz from the Jabberd 2 Releases page, where "n" is the latest version of Jabberd 2.

Download the file referenced above into a convenient directory for building the installation files. At the time of writing, Jabberd 2.1.21 is the latest version and is used in the examples below.

=== A.1.6.2. Extract Jabberd Installation Files

Change to the directory where you downloaded the file above and then extract the Jabberd 2 files by running the command: 

        tar -zxvf jabberd-2.1.21.tar.gz

=== A.1.6.3 Configure the Jabberd Build

Change to the directory created above: 

        cd jabberd-2.1.21
        ./configure --enable-sqlite --enable-ssl

The command above will configure your build to use SQLite as the data store. You may also wish to enable debugging. To do this, add --enable-debug to the configuration options above. For help with configuration options, enter ./configure --help.

=== A.1.6.4. Build Jabberd

Build Jabberd buy running the command: 

        make

=== A.1.6.5. Install Jabberd

Switch to the super-user: 

        su

Run make install: 

        make install

A.1.6.7. Default File Locations

Your Jabberd 2 installation is complete. Below is a listing of file locations for the default installation: 

        /usr/local/etc    Jabberd Configuration Files
        /usr/local/bin    Jabberd Binaries (jabberd, c2s, resolver, router, s2s, sm)

A.1.7. Create Database

You should create database for jabberd (default location is /usr/local/var/jabberd/db/sqlite.db): 

         sqlite3 /usr/local/var/jabberd/db/sqlite.db <tools/db-setup.sqlite

A.1.8. Configure Server

The most basic Jabberd configuration (when using SQLite) requires a total of 4 configuration edits:

  1. Set hostname ID in c2s.xml
  2. Set authreg module to use in c2s.xml
  3. Set hostname ID in sm.xml
  4. Set storage module to use in sm.xml

The configuration files are all found in /usr/local/etc/jabberd.

A.1.8.1. Set hostname ID in c2s.xml

In c2s.xml edit the id tag under the section labelled local network configuration so that the id references a resolvable network name for your jabber server. For example, using the FQDN of somemachine.somedomain.com, your c2s.xml configuration would appear as below: 

        <local>
          <!-- Who we identify ourselves as. This should correspond to the
               ID (host) that the session manager thinks it is. You can
               specify more than one to support virtual hosts, as long as you
               have additional session manager instances on the network to
               handle those hosts. The realm attribute specifies the auth/reg
               or SASL authentication realm for the host. If the attribute is
               not specified, the realm will be selected by the SASL
               mechanism, or will be the same as the ID itself. Be aware that
               users are assigned to a realm, not a host, so two hosts in the
               same realm will have the same users.
               If no realm is specified, it will be set to be the same as the
               ID. -->
          <id>somemachine.somedomain.com</id>

Note that this id must be resolvable by the clients that will be connecting to your Jabberd server. Using an IP address as the id should work; however, this is strongly discouraged.

A.1.8.2. Set authreg module to use in c2s.xml

Further down in c2s.xml is a section labeled Authentication/registration database configuration. This is where the authreg data module is specified. Edit the module tag so that SQLite is specified as the Backend module to use. Throughout Jabberd configuration, SQLite is abbreviated to sqlite. Therefore, you should edit the module tag as below: 

        <!-- Authentication/registration database configuration -->
        <authreg>
          <!-- Backend module to use -->
          <module>sqlite</module>

A.1.8.3. Set hostname ID in sm.xml

At the top of sm.xml is the id setting for hostname. Edit the id tag with the same hostname specified in section A.1.6.1 above: 

        <sm>
          <!-- Our ID on the network. Users will have this as the domain part of
               their JID. If you want your server to be accessible from other
               Jabber servers, this ID must be resolvable by DNS.s
               (default: localhost) -->
          <id>somemachine.somedomain.com</id>

A.1.8.4. Set storage module to use in sm.xml

Further down in sm.xml is a section labeled Storage database configuration. This is where the storage data module is specified. Edit this section as below so that SQLite is specified as the storage data driver to use: 

          <!-- Storage database configuration -->
          <storage>
            <!-- By default, we use the MySQL driver for all storage -->
            <driver>sqlite</driver>

A.1.9. Test Server

If you have created the logging and data directories specified above, you should be able to start your Jabberd 2 server and connect to it.

A.1.9.1. Starting Jabberd 2

Start your Jabberd 2 server by using the start up script: 

        su
        su jabber
        /usr/local/bin/jabberd

If your server fails to start, you can start Jabberd 2 with the debug option (note that this requires building Jabberd 2 with the debug option — see section A.1.5.3 above): 

        /usr/local/bin/jabberd -D

A.1.9.2. Connecting to your Jabberd Server

You should now be able to connect to your Jabberd server, and create a new account. Your account name should be something like someuser@…. (As noted above, use only lowercase letters in account names.) If you are unable to connect, make certain that the hostname used (sections A.1.6.1 and A.1.6.3) is resolvable from the machine on which the client is running.

A.1.10. Further Configuration

Once your server is running, you may wish to configure it further. See especially Section 5, Common Configuration Tasks, for further information about Jabberd configuration.

© 2003 Will Kamishlian and Robert Norris

http://jabberd.jabberstudio.org/2/docs/ccommons.gifThis work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.