Jabberd 2 Installation and Administration Guide

jabberd 1.4 only

      su
      groupadd jabber
      useradd -g jabber jabber

      su
      mkdir -p /usr/local/var/jabberd/pid/
      chown -R jabber:jabber /usr/local/var/jabberd/pid/     

      mkdir -p /usr/local/var/jabberd/log/
      chown -R jabber:jabber /usr/local/var/jabberd/log

      tar -zxvf  jabberd-2.0s3.tar.gz 

      cd jabberd-2.0s3

      ./configure --help

      ./configure --enable-mysql --enable-ssl --enable-idn

      ./configure --enable-db --enable-debug --enable-ssl --enable-idn

      ./configure --enable-pgsql --enable-ssl --enable-idn \
      --with extra-include-path=/usr/local/include:/usr/local/include/mysql \
      --with-extra-library-path=/usr/local/lib:/usr/local/lib/mysql

      ./configure

      make

      su

      make install

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

      chown -R root:jabber /usr/local/etc/jabberd/*

      chmod -R 640 /usr/local/etc/jabberd/*

      ln -s /usr/local/etc/jabberd/ /etc/jabberd

      <!-- Session manager configuration -->
      <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>    

      <!-- Local network configuration -->
      <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>        

       mkdir -p /usr/local/var/jabberd/db
       chown -R jabber:jabber /usr/local/var/jabberd

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

      <!-- Berkeley DB driver configuration -->
      <db>
        <!-- Directory to store database files under -->
        <path>/usr/local/var/jabberd/db</path>

        <!-- Synchronize the database to disk after each write. If you
             disable this, database accesses may be faster, but data may
             be lost if jabberd crashes. -->
        <sync/>
      </db>      

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

      <!-- Berkeley DB module configuration -->
      <db>
        <!-- Directory to store database files under -->
        <path>/usr/local/var/jabberd/db</path>

        <!-- Synchronize the database to disk after each write. If you
             disable this, database accesses may be faster, but data may
             be lost if jabberd crashes. -->
        <sync/>
      </db>   

      mysql -u root -p
      mysql>\. db-setup.mysql

      GRANT select,insert,delete,update ON jabberd2.* 
      to jabberd2@localhost IDENTIFIED by 'secret';

      ln -s /var/lib/mysql/mysql.sock /tmp/mysql.sock   

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

      <!-- MySQL driver configuration -->
      <mysql>
        <!-- Database server host and port -->
        <host>localhost</host>
        <port>3306</port>

        <!-- Database name -->
        <dbname>jabberd2</dbname>

        <!-- Database username and password -->
        <user>jabberd2</user>
        <pass>secret</pass>

        <!-- Transaction 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. -->
        <transactions/>
      </mysql>

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

      <!-- MySQL module configuration -->
      <mysql>
        <!-- Database server host and port -->
        <host>localhost</host>
        <port>3306</port>

        <!-- Database name -->
        <dbname>jabberd2</dbname>

        <!-- Database username and password -->
        <user>jabberd2</user>
        <pass>secret</pass>
      </mysql>

      createdb -U postgres jabberd2

      createdb -U postgres -E UNICODE jabberd2

      createuser -P -U postgres jabberd2

      Enter password for user "jabberd2":
      Enter it again:
      Shall the new user be allowed to create databases? (y/n) n
      Shall the new user be allowed to create more new users? (y/n) n
      CREATE USER

      psql -U jabberd2 jabberd2

      jabberd2=>\i db-setup.pgsql

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

      <!-- PostgreSQL driver configuration -->
      <pgsql>
        <!-- Database server host and port -->
        <host>localhost</host>
        <port>5432</port>

        <!-- Database name -->
        <dbname>jabberd2</dbname>

        <!-- Database username and password -->
        <user>jabberd2</user>
        <pass>secret</pass>

        <!-- Transaction support. If this is commented out, transactions
             will be disabled. This might make database accesses faster,
             but data may be lost if jabberd crashes. -->
        <transactions/>
      </pgsql>

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

      <!-- PostgreSQL module configuration -->
      <pgsql>
        <!-- Database server host and port -->
        <host>localhost</host>
        <port>5432</port>

        <!-- Database name -->
        <dbname>jabberd2</dbname>

        <!-- Database username and password -->
        <user>jabberd2</user>
        <pass>secret</pass>
      </pgsql>

      cp /etc/pam.d/system-auth /etc/pam.d/jabberd

      auth       required     pam_winbind.so
      password   required     pam_winbind.so
      account    required     pam_winbind.so
      session    required     pam_winbind.so      

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

      <!-- Registration configuration -->
      <register>
        <!-- Account registration is enabled by default (provided the
             auth/reg module in use supports it). Comment this out to
             disable. -->
        <!-- <enable/> -->

      <!-- User options -->
      <user>
        <!-- By default, users must explicitly created before they can start
             a session. The creation process is usually triggered by a c2s
             component in response to a client registering a new user.

             Enableing this option will make it so that a user create will be
             triggered the first time a non-existant user attempts to start
             a session. This is useful if you already have users in an
             external authentication database (eg LDAP) and you don't want
             them to have to register. -->
        <auto-create/>

      allow bind_v2

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

      <!-- LDAP module configuration -->
      <ldap>
        <!-- LDAP server host and port (default: 389) -->
        <host>ldap.example.com</host>
        <port>389</port>

        <!-- Use LDAP v3 if possible. If disabled, v2 will be used.
             Encryption options are only available if v3 is enabled. -->
        <!--
        <v3/>
        -->

        <!-- Encryption. If enabled, this will create an encrypted channel
             to the LDAP server using the LDAP STARTTLS mechanism. -->
        <!--
        <starttls/>
        -->

        <!-- Encryption. If enabled, this will create an encrypted channel
             to the server using the old-style "ldaps://" mechanism. It is
             recommended that you use <starttls/> instead of this. -->
        <!--
        <ssl/>
        -->

      <!-- DN to bind as for searches. If unspecified, the searches
           will be done anonymously. -->
      <!--
      <binddn>cn=Directory Manager</binddn>
      <bindpw>secret</bindpw>
      -->

      <!-- LDAP attribute that holds the user ID (default: uid) -->
      <uidattr>uid</uidattr>

      <!-- base DN of the tree. You should specify a DN for each
           authentication realm declared in the <local/> section above,
           by using the realm attribute. -->
      <basedn realm='company'>o=Company.com</basedn>
      <basedn>o=Example Corp.</basedn>
    </ldap>        

      <!-- LDAP module configuration -->
      <ldap>
        <!-- LDAP server host and port (default: 389) -->
        <host>ldap.mydomain.org</host>
        <port>389</port>

        <!-- Use LDAP v3 if possible. If disabled, v2 will be used.
             Encryption options are only available if v3 is enabled. -->

        <v3/>

        <!-- Encryption. If enabled, this will create an encrypted channel
             to the LDAP server using the LDAP STARTTLS mechanism. -->

        <starttls/>

        <!-- Encryption. If enabled, this will create an encrypted channel
             to the server using the old-style "ldaps://" mechanism. It is
             recommended that you use <starttls/> instead of this. -->
        <!--
        <ssl/>
        -->

        <!-- DN to bind as for searches. If unspecified, the searches
             will be done anonymously. -->

        <!--
        <binddn>cn=admin,dc=mydomain,dc=org</binddn>
        <bindpw>snip</bindpw>
        -->          

        <!-- LDAP attribute that holds the user ID (default: uid) -->
        <uidattr>uid</uidattr>

        <!-- base DN of the tree. You should specify a DN for each
             authentication realm declared in the <local/> section above,
             by using the realm attribute. -->

        <basedn>ou=people,ou=design,dc=mydomain,dc=org</basedn>
      </ldap>      

      <!-- Registration configuration -->
      <register>
        <!-- Account registration is enabled by default (provided the
             auth/reg module in use supports it). Comment this out to
             disable. -->
        <!-- <enable/> -->

      <!-- User options -->
      <user>
        <!-- By default, users must explicitly created before they can start
             a session. The creation process is usually triggered by a c2s
             component in response to a client registering a new user.

             Enableing this option will make it so that a user create will be
             triggered the first time a non-existant user attempts to start
             a session. This is useful if you already have users in an
             external authentication database (eg LDAP) and you don't want
             them to have to register. -->
        <auto-create/>

    su
    su jabber
    cd /usr/local/bin
    ./jabberd  

    /usr/local/bin/jabberd -D

        <!-- File containing a SSL certificate and private key for client
             connections. If this is commented out, clients will not be
             offered the STARTTLS stream extension -->

        <pemfile>/usr/local/etc/jabberd/server.pem</pemfile>

        <ssl-port>5223</ssl-port>

        <!-- Require STARTTLS. If this is enabled, clients must do STARTTLS
             before they can authenticate. Until the stream is encrypted,
             all packets will be dropped. -->

        <require-starttls/>

        router.xml
        sm.xml
        resolver.xml
        s2s.xml
        c2s.xml

        <!-- Router connection configuration -->
        <router>
          <!-- IP/port the router is waiting for connections on -->
          <ip>127.0.0.1</ip>      <!-- default: 127.0.0.1 -->
          <port>5347</port>       <!-- default: 5347 -->

          <!-- Username/password to authenticate as -->
          <user>jabberd</user>    <!-- default: jabberd -->
          <pass>secret</pass>     <!-- default: secret -->

          <!-- File containing a SSL certificate and private key to use when
               setting up an encrypted channel with the router. If this is
               commented out, or the file can't be read, no attempt will be
               made to establish an encrypted channel with the router. -->

          <pemfile>/usr/local/etc/jabberd/server.pem</pemfile>

      <users>
        <user>
          <name>jabberd</name>
          <secret>newpass</secret>
        </user>
      </users>    

      <!-- Router connection configuration -->
      <router>
        <!-- IP/port the router is waiting for connections on -->
        <ip>127.0.0.1</ip>      <!-- default: 127.0.0.1 -->
        <port>5347</port>       <!-- default: 5347 -->

        <!-- Username/password to authenticate as -->
        <user>jabberd</user>    <!-- default: jabberd -->
        <pass>newpass</pass>     <!-- default: secret -->

      <!-- Access control information -->
      <aci>
        <!-- The usernames listed here will get access to all restricted
             functions, regardless of restrictions further down -->
        <acl type='all'>
          <user>jabberd</user>
        </acl>

      <acl type='all'>  
        <jid>admin@lsomedomain.com</jid>
      </acl>     

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

        <!-- Registration configuration -->
        <register>
          <!-- Account registration is enabled by default (provided the
               auth/reg module in use supports it). Comment this out to
               disable. -->
          <!--
          <enable/>
          -->

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

        <!-- Registration configuration -->
        <register>
          <!-- Account registration is enabled by default (provided the
               auth/reg module in use supports it). Comment this out to
               disable. -->
          <enable/>

          <!-- Human-readable instructions to be returned to client when
               registration is requested. -->
          <instructions>Enter a username and password to register with this server.</instructions>

          <!-- Password change only. When registration is disabled, it may
               still be useful to allow clients to change their password. If
               you want this, uncomment this when you disable registration. -->
          <password/>

        _jabber._tcp.<domain>   ->    <host>.<domain>:5269
        _xmpp-server._tcp.<domain>    ->    <host>.<domain>:5269 
        _xmpp-client._tcp.<domain>    ->    <host>.<domain>:5222      

        _jabber._tcp.some_domain.com. 86400 IN SRV 5 0 5269 host.some_domain.com.
        _xmpp-server._tcp.some_domain.com. 86400 IN SRV 5 0 5269 host.some_domain.com.
        _xmpp-client._tcp.some_domain.com. 86400 IN SRV 5 0 5222 host.some_domain.com.       

            :_jabber._tcp.some_domain.com:33:\000\012\000\000\024\225\004host\013some_domain\003com\000 
            :_xmpp-client._tcp.some_domain.com:33:\000\012\000\000\024\146\004host\013some_domain\003com\000 
            :_xmpp-server._tcp.some_domain.com:33:\000\012\000\000\024\225\004host\013some_domain\003com\000

        dig @my.dns_server.com _jabber._tcp.some_domain.com any +short

        10 0 5269 host.some_domain.com.

        <xdb id="xdb">
          <host>conference.somedomain.com</host>

          <load>
            <xdb_file>/usr/local/jabber/xdb_file/xdb_file.so</xdb_file>
          </load>

          <xdb_file xmlns="jabber:config:xdb_file">
            <spool>/usr/local/var/spool/jabber</spool>
          </xdb_file>
        </xdb>      

        <log id="muclog">
          <file>/usr/local/var/jabberd/log/muc.log</file>
          <host/>
          <logtype/>
          <format>%d: [%t] (%h): %s</format>
        </log>      

        <service id="muclinker">
          <uplink/>
          <connect>
            <ip>192.168.0.2</ip> <!-- IP Address of Router here -->
            <port>5347</port>

        <service id="muclinker">
          <uplink/>
          <connect>
            <ip>192.168.0.2</ip> <!-- IP Address of Router here -->
            <port>5347</port>
            <secret>ComponentPass</secret>
          </connect>
        </service>      

        <!-- Local network configuration -->
        <local>
          <!-- IP address to bind to (default: 0.0.0.0) -->
          <ip>0.0.0.0</ip>
          <!-- Port to bind to (default: 5347) -->
          <port>5347</port>
          <!-- File containing the user table. This is where the router gets
               its component and secret information from for component
               authentication.-->
          <users>/usr/local/etc/jabberd/router-users.xml</users>
          <!-- Shared secret used to identify legacy components (that is,
               "jabber:component:accept" components that authenticate using
               the "handshake" method). If this is commented out, support for
               legacy components will be disabled. -->
          <secret>ComponentPass</secret>

        <!-- Name aliases.

             Packets destined for the domain specified in the "name" attribute
             will be routed to the component that has currently bound the name
             in the "target" attribute (assuming it is online).

             This is usually only required for some kinds of legacy
             components (particularly jabberd 1.4 "uplink" components) -->
        <aliases>
          <!-- Example for a msn transport running from a jabberd 1.4 uplink -->
          <!--
          <alias name='msn.domain.com' target='msn-linker'/>
          -->
          <alias name='conference.somedomain.com' target='muclinker'/>
        </aliases>      

        <jabber>

          <service id="muclinker">
            <uplink/>
            <connect>
              <ip>192.168.0.2</ip> <!-- IP Address of Router here -->
              <port>5347</port>
              <secret>ComponentPass</secret>
            </connect>
          </service&

Convention	Name	Description
P	Parameter	Information about your specific setup that you will enter into a configuration file, etc.
C	Checkpoint	A point at which to stop and check your setup.
N	Note	An informational note.
I	Important	An important note or warning.
F	Required Files	Software or specific files needed to complete a step or series of steps.
O	Optional Step	A step that is not required for the most basic installation.
E	External System	A step that may require configuration on an external system, such as a router.

Parameter	Required	Section(s)	Description	Your Information
Jabberd User and Group	Y	2.2	The Linux (or other OS) user and group that will be used to run Jabberd	user: jabber group: jabber
PID Directory	Y	2.3	Directory in which Jabberd stores PID Files	/usr/local/var/jabberd/pid
Log Directory	N	2.3	Directory for Jabberd logs. If not specified in configuration files, logging defaults to syslog.	/usr/local/var/jabberd/log
Authentication Package	Y	2.4.3 3.3,	Third party package to be used for Jabberd authentication management	MySQL, PostgreSQL, Berkeley DB, OpenLDAP or PAM
Data Storage Package	Y	2.4.4 4.3	Third party package to be used for storage of Jabberd data	MySQL, PostgreSQL or Berkeley DB
Data Directory	Berkeley DB	4.1.1, 4.2.1,	Directory for Berkeley DB data files	/usr/local/var/jabberd/db
MySQL User and Password	MySQL	3.5.2.2, 4.1.2, 4.2.2,	MySQL user and password that Jabberd uses to connect to MySQL	user: jabberd2 password: secret
PostgreSQL User and Password	PostgreSQL	3.5.3.1, 1 3, 4.2.3,	PostgreSQL user and password that Jabberd uses to connect to PostgreSQL	user: jabberd2 password: secret
OpenLDAP Connection Settings	OpenLDAP	2 5	Connection settings for your OpenLDAP server: FQDN for LDAP server (or IP), port, and LDAP version used (either v2 or v3)
OpenLDAP User and Password	OpenLDAP	4.2.5	User and password needed to connect to your OpenLDAP server. Required only if your OpenLDAP server does not permit anonymous binding (access)
OpenLDAP Query Settings	OpenLDAP	4.2.5	Base DN (distinguished name) and User ID attribute used to build queries for the OpenLDAP server. Base DN can be either the server root DN or an RDN (relative distinguished name) under which User ID's are found.
Hostname	Y	4.4	Hostname on which your Jabberd server is to be installed. For Internet accessible servers, this would be something like `somedomain.com`
SSL Key Location	N	5.3.1, 5.3.2	Location of OpenSSL pemfile. Required for SSL-encrypted communication	/usr/local/etc/jabberd/server.pem
Router User and Password	N	5.4	User and password used for component connections with the Jabberd Router component	user: jabberd2 password: secret

Jabberd 2 Installation and Administration Guide

Table of Contents

Appendices (including Quickstart Guide and FAQ):

1. Introduction

1.1. Purpose and Scope

1.2. Required Background

1.3. How to Use This Document

1.4. Conventions Used in this Document

Table 1.4. Document Conventions Used in this Guide

1.5. Further Reading

1.6. Legalese

1.7. Sources

2. Preparation for Jabberd 2

2.1. Gather Required Information

2.2. Create Jabber User and Group

2.3. Create Directories for PID's and Logs

2.4. Install Prerequisites

2.4.1. OpenSSL

2.4.2 Libidn

2.4.3. Data Storage Package

2.4.4. Authentication Package

3. Install Jabberd 2

3.1. Download Jabberd 2

3.2. Extract Jabberd Installation Files

3.3. Configure the Jabberd Build

3.4. Build Jabberd

3.5. Install Jabberd

3.6. Default File Locations

3.7. Set Ownership of Configuration Files

4. Basic Configuration

4.1. Set Host Name in sm.xml and c2s.xml

4.2. Provision and Configure for Storage and Authentication Package(s)

4.3. Provision and Configure for Berkeley Berkeley DB

4.3.1. Provisioning Berkeley DB

4.3.2. Configure for Storage using Berkeley DB (sm.xml)

4.3.3. Configure for Authentication using Berkeley DB (c2s.xml)

4.4. Provision and Configure for MySQL

4.4.1. Provision for MySQL

4.4.2. Configure for Storage using MySQL (sm.xml)

4.4.3. Configure for Authentication using MySQL (c2s.xml)

4.5. Provision and Configure for PostgreSQL

4.5.1. Provision PostgreSQL

4.5.2. Configure for Storage using PostgreSQL (sm.xml)

4.5.3. Configure for Authentication using PostgreSQL (c2s.xml)

4.6. Provision and Configure for PAM

4.6.1. Provision for PAM

4.6.2. Configure for Authentication using PAM (c2s.xml)

4.7. Provision and Configure for OpenLDAP

4.7.1. Provision for OpenLDAP

4.7.2. Configure for Authentication using OpenLDAP (c2s.xml)

4.8. Test Server

5. Common Configuration Tasks

5.1. Configuring Firewall for Internet Access

5.2. Configuring Jabberd 2 for SSL Connections

5.2.1. Assigning a Certificate for Use by Jabber Clients

5.2.2. Assigning a Certificate for Use by Jabberd Components

5.3. Changing Router Password

5.4. Creating an Administrative User

5.5. Disabling Public Registration

5.6. Enabling User Password Change

5.7. Setting DNS SRV Records

5.7.1. SRV Records for Jabberd

5.7.2. Creating SRV Records in Bind

5.7.3. Creating SRV Records in TinyDNS

5.7.4. Testing SRV Records

5.8. Using Jabberd 1.4 to Connect to Legacy Services

5.8.1. XDB Section

5.8.2. Log Section

5.8.3. Router IP Address and Port

5.8.4. Shared Password

5.8.5. Router Name Alias

5.8.6. Example: muc.xml

4.1. Set Host Name in `sm.xml` and `c2s.xml`

4.3.2. Configure for Storage using Berkeley DB (`sm.xml`)

4.3.3. Configure for Authentication using Berkeley DB (`c2s.xml`)

4.4.2. Configure for Storage using MySQL (`sm.xml`)

4.4.3. Configure for Authentication using MySQL (`c2s.xml`)

4.5.2. Configure for Storage using PostgreSQL (`sm.xml`)

4.5.3. Configure for Authentication using PostgreSQL (`c2s.xml`)

4.6.2. Configure for Authentication using PAM (`c2s.xml`)

4.7.2. Configure for Authentication using OpenLDAP (`c2s.xml`)