Jabberd 2 Documentation Project
Jabberd 2 Documentation Project
|
Before delving into detailed Jabberd configuration, this section attempts to provide a guide for the most common Jabberd configuration tasks:
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:
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, resolver, 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.
router, sm, resolver,
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.
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>
Your server is now ready for STARTTLS/SSL connections. You need only restart the C2S component for the SSL change to take effect.
require-starttls tag as below:
<!-- 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/>
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
resolver.xml
s2s.xml
c2s.xml
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.
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,
resolver.xml, s2s.xml and c2s.xml.
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,
resolver.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.
router.xml Must Be Edited If User
Is Changed
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 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 Authentication/registration database configuration
section, look for the Registration configuration subsection.
Commenting the enable tag as below will disable public
registration:
<!-- 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/>
-->
Configurations using either PAM or OpenLDAP should disable public registration because Jabberd 2 does not support public registration via PAM or OpenLDAP.
User password changing is disabled by default in Jabberd 2. To allow your
users to change their own passwords, uncomment the password
tag in the authreg section in c2s.xml as below:
<!-- 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/>
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.
somedomain.com resolves
host1.somedomain.com, and your Jabberd server is running on
host1, SRV records would not be required.
There are 3 SRV records that can be created for a Jabberd installation:
_jabber._tcp.<domain> -> <host>.<domain>:5269
_xmpp-server._tcp.<domain> -> <host>.<domain>:5269
_xmpp-client._tcp.<domain> -> <host>.<domain>:5222
The first and second of these specify the host and the port for server-to-server (s2s) communications. There are two listings for this because the new XMPP protocol, regarding SRV records, is replacing the older Jabber standards. The third 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:
_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.
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 Anders
Brownworth'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':
:_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
Use 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 _jabber._tcp.some_domain.com any +short
This 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:
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>
/usr/local/jabber/jabberd/jabberd -c /etc/jabber/muc.xml
The -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.
NOTE (2012): The following section (5.9) has been deprecated because the Jabber Component Runtime source code no longers seems to be available. Also, JCR may no longer likely be necessary for transport installations.
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:
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.gz
JCR 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.
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:
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 DBI
For more information about these modules, see the CPAN site. The easiest way to install these,
along with any dependencies, is to use Perl's -MCPAN interface. To invoke
the -MCPAN interface and install Perl modules, enter the
cpan
shell by running this command (as super-user):
perl -MCPAN -e shell
If 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 DBI
Once 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:
./createDB
After 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.
config.xml
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>
hostname value to provide the hostname of
your Jabberd 2 server. This should match the id at the top
of sm.xml.port to provide the port number that the
Jabberd 2 router is listening on. By default, this would be
5347.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.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.username to provide the MySQL user (from step
5.10.4.). For default installations, the username will be
jabberd2.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.
users-agent
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.
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.
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.
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.
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.
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.patch
Edit 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.
|
|
|
|
||||
|
|
||||
|
© 2003 Will Kamishlian and Robert Norris
|
||||
|
|
||||
| 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. | ||||
|
|
||||
|
|
 |
||