-
Notifications
You must be signed in to change notification settings - Fork 172
InstallGuide CommonConfigurationTasks
Go up: InstallGuide
Before delving into detailed Jabberd configuration, this section attempts to provide a guide for the most common Jabberd configuration tasks:
- Configuring Firewall for Internet Access
- Configuring Jabberd 2 for SSL
- Changing Router Password
- Creating an Administrative User
- Disabling Public Registration
- Enabling User Password Change
- Setting DNS SRV Records
- Using Jabberd 1.4 to Connect to Legacy Services
- Using JCR to Connect to Legacy Services
- Setting up a JUD Using Users-Agent
- Integrating Users-Agent with vCard Data (private servers only)
Note that there are two options for connecting Jabberd 1.4 legacy services to your Jabberd 2 installation. Jabberd 2 can connect to services, such as conferencing and gateways, running within a Jabberd 1.4 process. Additionally, a component wrapper called JCR has been released, and this wrapper allows a Jabber 1.4 component (written in C) to be compiled and run as Jabberd 2 service. At the time of writing, JCR has been tested with MU Conferencing only.
Although firewall configuration is beyond the scope of this guide, administrators should be aware of the TCP ports that need to be enabled for Internet access:
- port 5222 -- non-SSL and STARTTLS client communication
- port 5223 -- SSL wrapper client communication
- port 5269 -- server to server communication
TCP ports should be enabled as above and according to your configuration if your Jabberd 2 installation is to access the Internet.
Jabberd 2 is designed to provide for STARTTLS and SSL connections not only between Jabber clients and the server, but also between the Jabberd server components (sm, s2s and c2s) and the Jabberd router. A single SSL certificate may be used for these two functions (Jabber client to Jabberd and Jabberd component to router), or two separate keys may be used. See the appendix, Generating a Self-Signed SSL Certificate for instructions about how to create your own self-signed certificate for use by Jabberd 2.
'''N''' Note: Self-Signed Certificates Not Trusted
Note that self-signed certificates are not automatically trusted by Jabber clients because there is no chain of authority against which to verify authenticity. Nevertheless, creating a self-signed certificate not only will allow your Jabber users to communicate over a secure channel (possibly with warnings displayed by the client), but also such a certificate will provide for secure communication among the five Jabberd components (router, sm, s2s and c2s).
The SSL key for Jabber clients is located in c2s.xml. Note that c2s.xml contains the location of the SSL key used by Jabber clients in addition to the location of the SSL key used for c2s to router communications.
'''P''' Parameter: SSL Key Location
Uncomment the pemfile (your SSL key) location under the section labeled Local network configuration, and edit it for the location of your SSL key. Note that if your PEM file is in the default location of /usr/local/etc/jabberd/server.pem, you need only uncomment this section as below:
<!-- 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> The change above will enable STARTTLS on port 5222. Older Jabber clients use port 5223 for SSL enabled communications. If you wish to support SSL on port 5223, uncomment the ssl-port tags:
<ssl-port>5223</ssl-port>You may also set per-domain STARTTLS certificates using the <id/> attribute:
<id ... pemfile='/usr/local/etc/jabberd/server.pem' ... >Your server is now ready for STARTTLS/SSL connections. You need only restart the C2S component for the SSL change to take effect.
'''N''' Note: Disabling Non-STARTTLS Communication
To require STARTTLS communications, add the require-starttls attribute to <id/> tag as below:
<local>
<!-- [...]
require-starttls
If this is enabled, clients must do STARTTLS
before they can authenticate. Until the stream is encrypted,
all packets will be dropped. -->
<id ... require-starttls='yes' ... />Each of the five Jabberd components has its own configuration for encrypted component-to-router communications. Thus, these five configuration files must be edited to provide secure communication among Jabberd components:
- `router.xml`
- `sm.xml`
- `s2s.xml`
- `c2s.xml`
'''P''' Parameter: SSL Key Location In each of the files above, uncomment the pemfile tag for router communications. In the router.xml file, the pemfile is specified under the section labeled Local network configuration. In each of the the remaining four configuration files above, the pemfile location is specified under the section labeled Router connection configuration. Uncomment this section and edit it to point to the location of your SSL key. For example, you would edit c2s.xml as below if you are using the default location for your SSL key:
<!-- 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> Restart your Jabberd server for the change to take effect.
TODO: change info about disabling non-ssl comms. Add info about requiring TLS
The Jabberd configuration files contain passwords used to connect to the router component because communications between components and the router occur by XML over TCP/IP. These passwords help to ensure that only your installed components can communicate with the router. The configuration file, router-users.xml, contains ID's and password(s) for components that are allowed to connect to the router. By default, the ID is jabberd and the password is secret.
Additionally, each of the components (except the router) has a user ID and password specified in its configuration file. This is the ID and password combination that the respective component uses to connect with the router. Thus, for a component to be able to connect to the router, the component must have a user and password pair specified in its configuration file, and that pair must match an ID and password pair in router-users.xml.
To improve security for your Jabberd installation, you should change the password. This involves changing the password in router-users.xml and then in sm.xml, s2s.xml and c2s.xml.
'''P''' Parameter: Router User and Password In order to change the password used for authentication by the router, first change the password in router-users.xml as below (replacing newpass with your new password):
<users>
<user>
<name>jabberd</name>
<secret>newpass</secret>
</user>
</users>Then, change the password in each of sm.xml, s2s.xml and c2s.xml. In each of these files there are tags for the router user in the router section. Change the password as below (replacing newpass with your new password):
<!-- 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 --> Restart your Jabberd server for the change to take effect.
'''N''' Note: Multiple Passwords Allowed Note that you can assign a user and ID for each of the components if you wish. '''N''' Note: router.xml Must Be Edited If User Is Changed Note that the above edits describe how to change the router password only. If the user name in router-users.xml is changed, then the user listed in the acl section of router.xml must also be changed:
<!-- 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> Settings for administrative users are contained in the aci section of sm.xml. By default, the administrative user is admin@localhost. In order to enable an administrative user that can be accessed remotely, change the jid to a user of your own choosing as below:
<acl type='all'>
<jid>admin@lsomedomain.com</jid>
</acl> You will also need to create this user manually or from a Jabber client. When logged in, the administrative user will receive notices for user creation, and the administrative user will also be able to discover all online users, receive help requests, send MOTD's (messages of the day), etc.
Note that the user above is granted access to all administrative functions. You can assign specific administrative functions to users by specifying the acl type. See the examples in the sm.xml file.
Restart your Jabberd server for the change to take effect.
By default, Jabberd set up allows public registration for all users, which is to say that any user who can connect to your server can create their own Jabberd user on your server. In order to prevent public registration, edit the c2s.xml configuration file.
Under the local IO configuration section, the <id/> section configures domains enabled. The existance of register-enable attribute allows public registrations. Removing the attribute will disable public registration:
<id>example.com</id>Configurations using either PAM or OpenLDAP should disable public registration because Jabberd 2 does not support public registration via PAM or OpenLDAP.
There is one problem with the change above - the registration process is used to change user password. Disabling it, disallows password changes too. You may wish to reenable this:
<id ... password-change='true' ...>example.net</id>Note that this will have no effect when using PAM or OpenLDAP for authentication because these packages do not permit password changing via Jabberd. Restart your Jabberd server for the change to take effect.
Jabberd 2, in addition to other Jabber clients and servers, is able to use DNS SRV records for hostname resolution. DNS SRV records allow for delegation of services — by port — to other hosts. Thus, if you want your Jabber server to run on a host that is not the primary domain host, you would most likely want to set DNS SRV records to delegate Jabber client and server services to another host or hosts.
'''N''' Note: SRV Records Required Only for Non-Primary Host Note that DNS SRV records are required only if your Jabberd server is running on a host other than the primary domain host and if you do not wish to include the host (machine) name in your Jabber ID. For example, if a DNS query for somedomain.com resolves host1.somedomain.com, and your Jabberd server is running on host1, SRV records would not be required.
There are 2 SRV records that can be created for a Jabberd installation:
_xmpp-server._tcp.<domain> -> <host>.<domain>:5269
_xmpp-client._tcp.<domain> -> <host>.<domain>:5222The first specify the host and the port for server-to-server (s2s) communications. The second listing above specifies host and port for unencrypted client communications (c2s).
The following are examples for creating a set of SRV records for the BIND server:
_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.Replace some_domain.com with your domain name and host with the name of the host, and do not omit the "." after the domain name.
TinyDNS does not have a format for SRV records; however, you can use Rob Mayoff's TinyDNS Record Maker to create TinyDNS SRV records. These TinyDNS SRV records were created for the host of host.some_domain.com using a priority of 10 and a weight of '0':
:_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\000Use TinyDNS Record Maker to create a set of records to be added to the TinyDNS data file.
Once the your DNS server is properly updated, you should test the listings using Dig. For example, to test the entry of _jabber._tcp.some_domain.com, using the DNS server my.dns_server.com, you would enter the command below:
dig @my.dns_server.com _xmpp-server._tcp.some_domain.com any +shortThis should provide you with the data from your DNS SRV record:
10 0 5269 host.some_domain.com.This section describes how to use an existing Jabberd 1.4 installation to connect legacy Jabberd 1.4 services, such as gateways and transports, to Jabberd 2. See the next section for using the JCR component to connect to legacy services. See Appendix 11 for a primer on how Jabberd 2 can use a Jabberd 1.4x process to run a transport.
A familiarity with Jabberd 1.4. is assumed, as is a working Jabberd 1.4 installation. Jabberd 1.4 setup and configuration is beyond the scope of this document; however, many excellent resources exist, including the Jadmin Archive and the Jabberd 1.4x Administration Guide.
Connecting Jabberd to a legacy service is similar to the means by which Jabberd 1.4 links to services; however there are several important differences when linking from Jabberd 2 to a Jabberd 1.4 service:
- The linked configuration file must have an XDB section
- The linked configuration file must have a log section
- The linked configuration file must specify the router IP address and port
- The linked configuration file and the router configuration file must share a password
- The router.xml file must contain an alias for the service
Additionally, a service namespace should exist in sm.xml if the component does not support discovery (disco). For example, MU Conference supports discovery, so no entry is required in sm.xml in order to make this service browsable. On the other hand, JUD (Jabber User Directory) does not support discovery; therefore, an entry would be required in sm.xml to make a JUD browsable by users. See sm.xml for examples.
The sub-sections below describe how to configure a David Sutton's MU Conference for Jabberd 1.4, and the example concludes with a working MU Conference configuration file. See MU Conference for downloads and more information about this component. MU Conference provides a multi-user chat room service for Jabberd.
When running a gateway or transport with Jabberd 1.4, the main Jabberd process handles XDB and logging functions. This is not the case when running such a component with Jabberd 2. Instead, the component should run in its own process, and the component should handle its own XDB and logging functions. That is to say that legacy components should be run in a process that is self-contained. Thus, if you have a component that is linked to a Jabberd 1.4. server, you should add an XDB section to the service configuration file:
<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>The XDB section above specifies the hostname, the XDB module to load, and the location to write the spool file(s).
As noted above, the component configuration file must also contain a logging section. You might add a section like this to the configuration file for your linked component:
<log id="muclog">
<file>/usr/local/var/jabberd/log/muc.log</file>
<host/>
<logtype/>
<format>%d: [%t] (%h): %s</format>
</log>In the case of an MU Conference gateway, I have specified the log above as muc.log. Each service should have a separate log file.
The linked component should specify the IP address and port that the router is listening on. The default port for the router is 5347, so the beginning of the id section of your linked file would look something like this:
<service id="muclinker">
<uplink/>
<connect>
<ip>192.168.0.2</ip> <!-- IP Address of Router here -->
<port>5347</port>The Jabberd 2 server uses a password for component connections. This password is similar to the shared secret that is used in Jabberd 1.4. Continuing with the example above, you should create a password for your legacy component to use. (In Jabberd 2, all legacy components share the same password with the router) This password, or secret, must be specified in your the configuration file for your linked component:
<service id="muclinker">
<uplink/>
<connect>
<ip>192.168.0.2</ip> <!-- IP Address of Router here -->
<port>5347</port>
<secret>ComponentPass</secret>
</connect>
</service> This secret must also be specified in your router.xml file. The secret is set in the section labeled 'local network configuration':
<!-- 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> Note that the password is specified with the secret tag in router.xml (as above), and not in the router-users.xml file.
The router.xml file must also contain an alias for the linked component, and the router.xml file provides an example for uplinking an MSN transport. Add an alias section for the component to which you are linking. Continuing with the example above, this alias would be set as below in 'router.xml':
<!-- 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> Note that the alias references the DNS-resolvable name for the component, and the target references the service id as specified in the linked component XML file (as shown in Section 5.5.4).
A working muc.xml file for MU Conferencing appears below:
<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>
<service id="conference.somedomain.com">
<load>
<conference>/usr/local/jabber/mu-conference/src/mu-conference.so</conference>
</load>
<conference xmlns="jabber:config:conference">
<public/>
<vCard>
<FN>Public Chatrooms</FN>
<DESC>This service is for public chatrooms.</DESC>
</vCard>
<history>50</history>
<logdir>/usr/local/var/jabberd/log/muc/</logdir>
<sadmin>
<user>admin@somedomain.com</user>
</sadmin>
<notice>
<join>has become available</join>
<leave>has left</leave>
<rename>is now known as</rename>
</notice>
</conference>
</service>
<log id="muclog">
<file>/usr/local/var/jabberd/log/muc.log</file>
<host/>
<logtype/>
<format>%d: [%t] (%h): %s</format>
</log>
<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>
</jabber>'''C''' Checkpoint: Test Your Legacy Component Once your legacy component is set up, you should start up the component by running it in a Jabberd 1.4 process using a command similar to this:
/usr/local/jabber/jabberd/jabberd -c /etc/jabber/muc.xmlThe -c parameter specifies a configuration file for Jabberd 1.4. After you restart your Jabberd 2 server, your new (legacy) service should be running. In the case of MU Conference, you should be able to set up multi-user chat rooms via a compatible client, or via the script included with the tarball.
Given the newness of the Jabberd 2 server, there are few components designed for use specifically with the Jabberd 2 server. Nevertheless, Paul Curtis has written a component wrapper called the Jabber Component Runtime that is designed to run legacy components as Jabberd 2 services. The Jabber Runtime Component (JCR) allows C language components for Jabberd 1.4 to be run as standalone processes that connect to Jabberd 2. At the time of writing, only MU Conference and the Yahoo! transport have been tested with JCR. See Appendix 11 for a primer on how JCR works with Jabberd 2.
The JCR wrapper produces a binary file that runs the transport or service. Essentially, this binary file provides all the services that a separate Jabberd 1.4x process would provide for a transport or service. The INSTALL file of the JCR package provides instructions for use, and good instructions can also be found on the MU Conference site.
The following is an example of the steps that one would take to create a JCR binary for the MU Conference service:
- Download JCR and MU Conference
- Build the JCR Library
- Build the Component
- Configure the Component
- Start the Component
At the time of writing, JCR 0.2.4 and MU Conference 0.6.0 are the latest versions and are used in this example.
Download the latest JCR package from the JCR Home Page, and the latest MU Conference package from the MU Conference Home Page into a working directory. Then, untar the JCR package:
tar -xzvf jcr-0.2.4.tar.gzJCR has one dependency, glib-2.0. You should check that this is installed on your system before building the JCR library.
Build the JCR library files after entering the JCR directory:
cd jcr-0.2.4
make I and others have noted that the build process produces errors starting with the word TERROR_. These errors did not prevent me from successfully using JCR.
Move the service package, in this case mu-conference-0.6.0.tar.gz, into the JCR directory, in this case jcr-0.2.4, and then untar the service package there:
mv ../mu-conference-0.6.0.tar.gz ./
tar -xzvf mu-conference-0.6.0.tar.gz Copy the JCR library files (main.c and jcomp.mk) to the src directory of the service:
cp src/main.c mu-conference-0.6.0/src/
cp src/jcomp.mk mu-conference-0.6.0/src/ Then cd to the src directory of the service and build the JCR component:
cd mu-conference-0.6.0/src/
make -f jcomp.mk The build process should create a binary (in the mu-conference/src/ directory) called mu-conference. This binary provides the MU Conference service for Jabberd 2. Copy this binary to a bin directory, such as /usr/local/bin.
The src directory of the JCR package contains an sample configuration file (muc_conf.xml) for use with MU Conference. Copy this file to the directory where your Jabberd 2 configuration files exist, such as /etc/jabberd or /usr/local/etc/jabberd.
Edit muc_conf.xml for your own installation. Within muc_conf.xml, set the directories for spool, logdir (there are 2 log directories) and pidfile. These should be set to directories over which your jabber user has permissions. (Note that spool refers to the spool directory.) Set the host to a name that is resolvable by your clients. Set the ip to the IP address or hostname of your Jabber server. Set the secret to match the secret used to identify legacy components in your router.xml file (found in the local section). You may also wish to set an administrator JID (sadmin).
Edit your router.xml file to provide an alias for this service. Under the Name aliases section, add an alias that identifies this service:
<alias name='conference.somedomain.com' target='linker'/>Where conference.somedomain.com is the host specified in mu_conf.xml, and linker is the name specified in mu_conf.xml.
Restart your Jabberd 2 server for the change to take effect, and then start the mu-conference binary:
su jabber
/usr/local/bin/mu-conference -c /etc/jabberd/muc-conf.xml Your Jabber users should now be able to browse the Public Chatrooms service, and they should be able to create and use group chatrooms. The mu-conference binary does not detach from the terminal when started. You may wish to use Daemon Tools to start mu-conference on boot.
Ryan Eatmon has updated his Users-Agent JUD (Jabber User Directory) package to work with Jabberd 2, and with some valuable help from John Hamill, I was able to get it running with my Jabberd 2 installation. Users-Agent is a Perl-based JUD that relies on MySQL for storage. Users-Agent is the JUD currently running on Jabber.org.
'''N''' Note: JUD and vCard Data are Not the Same Thing A JUD provides users with a searchable database from which they can locate contacts. A JUD is not a database of vCard data. vCard data is separate from a JUD database, so you should not expect that upon setting up a JUD that it will contain existing vCard data. Instead, users must provide data to the JUD by registering to it.
N Note: Fljud Provides LDAP and JUD Integration If you are using OpenLDAP for authentication, you may wish to look at the Fljud product. Fljud integrates a JUD with LDAP data.
I have documented the steps I followed to get Users-Agent up and running; however, I would be interested to hear how these steps work for others. A running Users-Agent package consists of three elements:
- users-agent (Perl script)
- config.xml (configuration file)
- JUD (MySQL database)
The users-agent script is the running program that provides the JUD service. The users-agent script relies on the config.xml file for configuration. The config.xml file must be in the same path from which users-agent is run — or the -c option must be used to specify the location of config-xml. users-agent stores all data in a MySQL database named JUD. The package comes with a script named createDB that sets up the JUD database.
Setup of Users-Agent consists of these 7 steps, which are detailed below:
1. Install Required Perl Modules 2. Download and Install Users-Agent 3. Create JUD Database 4. Set JUD Database Permissions 5. Configure config.xml 6. Test users-agent 7. Set Users-Agent to Start with Jabberd 2
The steps may seem complex; however, installation is actually straightforward, and I have tried to provide as much detail as possible.
Users-Agent relies on these three Perl modules:
Net::Jabber v1.30
XML::Stream v1.18
DBIFor more information about these modules, see the CPAN site. The easiest way to install these, along with any dependencies, is to use Perl's CPAN.pm install tool. To install the Perl modules, enter the cpan shell by running this command (as super-user):
perl -MCPAN -e shellIf this is the first time you have used the cpan shell, you will enter an interactive setup script. Once finished, you will be ready to install the packages above (while still in the cpan shell):
cpan> install Net::Jabber
cpan> install XML::Stream
cpan> install DBIOnce these are installed, you are ready to install Users-Agent. If you ever need to install additional Perl modules, you can enter the cpan shell by using the command above (perl -MCPAN -e shell).
Choose a directory where you would like to install Users-Agent. In the example below, User-Agent is installed under /etc/jabberd.
From your chosen directory, download the latest release of Users-Agent package from Jabberstudio.org. Users-Agent 1.1 is the current release and is used in the examples below.
Untar the Users-Agent package, and then switch to the directory just created:
tar -zxvf users-agent-1.1.tar.gz
cd users-agent-1.1 Users-Agent is now installed.
The Users-Agent package contains a createDB script that will create the MySQL JUD database. This script needs to temporary access an existing MySQL database as the means to connect to MySQL and install the JUD database. The easiest way to grant it access is to temporarily disable your MySQL root password by running this command:
mysqladmin -u root -p password ""Alternately, you may edit the createDB script so that lines 13 and 17 contain your MySQL root password (enter it between the empty quotes). However, if you do not disable your MySQL root password, you must also export the DBI_DRIVER environment variable prior to running createDB. The DBI_DRIVER variable should be set to a value of dbi:mysql:test:localhost, where test is a working MySQL database.
Once you have disabled your MySQL root password (or edited createDB and set the DBI_DRIVER variable), run the script to create your JUD database:
./createDBAfter you create the database, you should reset your MySQL root password:
mysqladmin -u root password "oldrootpassword"Then, you can check that the database was created by entering the mysql console:
mysql -u root -p
mysql> show databases;
+----------+
| Database |
+----------+
| JUD |
| jabberd2 |
| mysql |
| test |
+----------+
4 rows in set (0.00 sec) The JUD database is now setup.
After the JUD database is created, permissions need to be granted to it. If you are using MySQL for Jabberd 2 authentication or storage, you already have a MySQL user that can be used for the JUD database. If this is the case, enter the MySQL console and run this SQL statement to grant the MySQL user jabberd2 permissions to the JUD database (replace jabberd2 if you are not using the default MySQL user):
mysql -u root -p
mysql> use JUD;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'jabberd2'@'localhost' WITH GRANT OPTION; If you are using MySQL with Jabberd 2 and cannot remember the name for your MySQL user, open sm.xml or c2s.xml and scan down below MySQL driver configuration, where you will find the user and password (pass) that you are using to connect with Jabberd 2.
If you are not using MySQL for authentication or storage, you should run a slightly different SQL statement that will create a new MySQL user and password that users-agent will use to connect to MySQL (replace secret_password with a the password you wish to use for this MySQL user):
mysql -u root -p
mysql> use JUD;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'jabberd2'@'localhost'
-> IDENTIFIED BY 'secret_password' WITH GRANT OPTION; Once you have granted permissions, you can test them by using your jabberd2 user to start the MySQL console. You will need your jabberd2 MySQL password (created immediately above or found in sm.xml) to start the console:
mysql -u jabberd2 -p
mysql> use JUD;
mysql> select * from jud; You should receive output something like: Empty set (0.01 sec). Your JUD database is now ready for use by users-agent.
Users-Agent relies on config.xml for configuration. Open config.xml in a text editor. To get Users-Agent running, I edited the values between these 6 tags:
<hostname>
<port>
<secret>
<name>
<username>
<password> 1. Edit the hostname value to provide the hostname of your Jabberd 2 server. This should match the id at the top of sm.xml. 2. Edit port to provide the port number that the Jabberd 2 router is listening on. By default, this would be 5347. 3. Edit secret to provide the shared secret that the Jabberd 2 router uses to connect to legacy components. The shared secret you are currently using can be found in router.xml near the top. Look for the secret tag pair under the section labeled Local Network configuration. 4. Edit name to provide the hostname for the Users-Agent. This hostname is usually something like users.somedomain.com, users.jabber.somedomain.com, jud.somedomain.com, etc. This hostname must be resolvable via DNS if your clients are to access it over the Internet. 5. Edit username to provide the MySQL user (from step 5.10.4.). For default installations, the username will be jabberd2. 6. Edit password to provide the MySQL user password (from step 5.10.4.). Again, this password can be found in sm.xml or c2s.xml if you are already using MySQL with Jabberd 2.
users-agent is now configured for use.
You should now be ready to start and test users-agent. Make sure that your Jabberd 2 and MySQL servers are running. Then, start users-agent :
su jabber
./users-agent Users-Agent should start up without returning any errors, and it should not exit. Users-Agent does not put itself into the background, so it should remain running in the terminal.
Log into your server from a Jabber client. With users-agent running, you should be able to see Users-Agent as an available service. How your client displays this depends on the client. The Users-Agent service should offer both Register and Search options.
Your JUD database is empty, so you will need to register some users to test it. From your Jabber client, select Register (this is usually a right-click option in Jabber clients). You should be presented with the option of registering for this service along with a form into which you can enter personal information.
'''I''' Important: Choice of Client Affects Use of Agent During testing, I was not able to get Users-Agent to perform consistently across test clients. For Linux, PSI seemed to respond the best; however, PSI does not display a registration form the first time a user attempts to register. The user must register once and then re-register to add any data. On Windows, JAJC and Exodus performed the best; however, JAJC, did not provide register and search options when right-clicking on the Users-Agent. Selecting Discovery (info) did provide these options in JAJC. Exodus performed the best of all the clients I tested (PSI, Gabber, Gnome-Gabber, Kopete, Exodus, JAJC and Neos).
Now, you should be able to actually search the Users-Agent. From your client, return to this service and select Search. You should be presented with a search form.
'''I''' Important: Users-Agent Supports Partial Matching Users-Agent supports partial matching for searches. Wildcards are not needed and are not used.
You should be able to search for the user you just registered by searching on the first letter of any of the fields entered into the registration form.
Once you have Users-Agent configured and running, you may wish to add it to your "app_rc.html script to start and stop it with Jabberd 2, or you may choose to use Daemon Tools to monitor it.
'''I''' Important: User-Agent Dies if it Cannot Connect to Router users-agent will die if it cannot connect to the router component. This means that if your Jabberd 2 server is stopped or dies, users-agent will die and therefore need restarting. You may wish to use Daemon Tools to make sure that users-agent is always restarted if it cannot connect to the router.
I have written a patch for Users-Agent that sets Jabberd 2 vCard data as the data source for Users-Agent. Once applied, Users-Agent uses the Jabberd vCard table for searches and registration. Thus, user updates to their own vCards are reflected in Users-Agent JUD searches. Users are able to update their vCard data in the normal way, or they can update the fields captured by Users-Agent (first name, last name, nickname and email) through the Users-Agent registration procedure.
'''I''' Important: JUD and vCard Data SHOULD NOT Be Integrated on Public Servers This patch is intended for private Jabberd 2 servers only. On public servers, vCards represent personal information over which the user has complete control. A user is able to allow another user to view personal vCard data by either authorizing that user, or by manually registering to the JUD.
This patch is intended for private Jabberd 2 servers, such as may be used by corporations or education institutions. For these setups, it is often convenient for each user to be able to search a list of all users. Note, however, that even after this patch is applied, each user must create a vCard entry to become visible in the Users-Agent JUD.
'''I''' Important: Patch Not Tested Under Heavy Load This patch has not been tested under heavy load.
In order to apply the patch, first get Users-Agent running as in Section 5.10. Then, download the users-agent.vcard.patch into the directory where your users-agent file is installed. Apply the patch with this command:
patch -p0 < users-agent.vcard.patchEdit config.xml so that dbname is the name of your Jabberd 2 MySQL database (usually jabberd2). Edit the username and password if necessary. Restart users-agent, and it should now be connecting to Jabberd 2 vCard data.
© 2012 Will Kamishlian, Robert Norris and Tomasz Sterna
Image(http://jabberd.jabberstudio.org/2/docs/ccommons.gif, right)This 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.
