Jabber Instant Message Server Virtual Appliance

Table of Contents


1. Introduction
2. Installation
3. Connecting Clients
4. Command Line Utilities


A. Software Used
B. References
C. Disclaimer


This is a virtual server appliance intended to provide the means for small businesses or organizations to deploy reliable, secure instant messaging for their organization quickly and efficiently.  It uses open source technologies and protocols such as Linux and Jabber to provide this service.  This appliance will provide provide a simple, fully operational, SSL/TLS secured, Jabber IM environment for messaging and file transfers in less than five minutes of setup, and requires no previous experience with the Linux operating system or Jabber messaging to complete.

Jabber instant messaging provides businesses a compelling alternative to public messaging services such as Yahoo! and MSN.  By deploying instant messaging within the organization, complete control can be exercised over its accounts, and all communications and file transfers can be secured using SSL/TLS encryption, something that is critical when sensitive information is being discussed or transferred.  The Jabber protocol offers many features beyond basic IM service, such as multi-user conferences and transports to other instant messaging services.  This implementation of a Jabber service is intended to be simple and easy to setup.  Not all of Jabber's features are available, but the simplified feature-set significantly decreases the time taken in configuration.  This appliance can provide a fully functional Jabber server with SSL/TLS security for messages and file transfers less than five minutes from first boot.


To begin the installation, boot the virtual machine.  Login with the username 'root' and the password 'password'.  A setup wizard will proceed through the remainder of the configuration.  A sample installation is presented below, with notes added at several points.

Network configuration:
The hostname will be the second portion
of the users' Jabber IDs, which take the mode
name@my.host.dom. In the example below,
this is name@jabber.company.com
Enter the fully qualified hostname
  (eg, jabber.company.com) []: jabber.company.com
While using DHCP is possible, it is recommended to define
a static IP and create an associated entry in DNS or, if
making a DNS entry is not possible, in the 'hosts' of each
client. The end of this section contains more information
about this issue.
Use DHCP to configure network settings?
  (Yes/No) [no]:

  Enter the IP address to use
  (eg, []:

  Enter the subnet mask to use
  (eg, []:

  Enter the address of the default gateway
  (eg, []:

  Enter the address of the primary DNS server
  (eg, []:

  Enter the address of the secondary DNS server
  (eg, (opt.) []:

Jabber server configuration:
If this is selected, unencrypted client connections
will not be allowed.
Require secure (SSL/STARTTLS) client connections?
  (Yes/No) [yes]:
Specify 'yes' if all clients will be on the same
network (or VPN) as the server. 'No' will allow
connections from other subnets and is proper
if the server will be accessible publicly, such
as over the Internet.
Allow client connections only from the local subnet? [no]: yes

Review configuration:
    Hostname:                   jabber.company.com
    IP Address:       
    Subnet Mask:      
    Default Gateway:  
    Primary DNS:      
    Secondary DNS:
    Require encryption: yes
    Local clients only: yes

Configuration OK? (Yes/No) [yes]:

When the configuration is accepted, a new SSL certificate
is created using the new hostname, and other configuration
files are updated.

Generating a 1024 bit RSA private key
writing new private key to 'privkey.pem'
writing RSA key
After entering a new password, press "Enter" to reboot
and the appliance configuration is complete!

Tip: If you are running setup to reconfigure the server
instead of for first installation and don't wish to set a
new password or restart right now, press Ctrl-C,
then restart the services with '/etc/rc.d/rc.inet1 restart &&
/etc/rc.d/rc.jabberd restart'

Please reset the root password:
Changing password for root.
Enter the new password (minimum of 5, maximum of 127 characters)
Please use a combination of upper and lower case letters and numbers.
New password:
Re-enter new password:
Password changed.

The appliance must be restarted now to finish
setup. Once the appliance has rebooted, clients can
begin connecting immediately. Press 'Enter' to continue.

Broadcast message from root (tty1) (Wed May 24 22:25:22 2006):

The system is going down for reboot NOW!

As soon as the appliance has rebooted, clients can begin connecting.  See Section 3 - Connecting Clients, for more details.

An entry will be needed in your DNS server or, if your organization does not provide one, in the 'hosts' file of your clients so that the server's name can be resolved.  One exception to this rule is using the Spark IM client, which provides a means of specifying the address of the Jabber server directly.  Configuring DNS is beyond the scope of this document; links to the homes of several DNS implementations, including BIND and Microsoft's DNS services, are provided in Appendix B.


If manual configuration via 'hosts' is necessary, all that must be done is to add an entry in each client similar to the following:

#IP                             #Hostname            jabber.myserver.com

The file is usually located at '/etc/hosts' on Linux and Unix machines, and at 'C:\Windows\system32\drivers\etc\hosts' on Windows machines.  Rarely, Unix-style machines may also need the file '/etc/nsswitch.conf' to be altered so that the 'hosts' file is consulted.  The word "files" should appear first in the list that follows on the line beginning with "hosts:".  Before changing nsswitch.conf, you should refer to the documentation for your particular system to make sure of any other requirements.

Connecting Clients:

There are many quality instant messaging clients for the Jabber protocol.  This documentation covers the initial configuration for three popular, no-cost, cross-platform clients.  The clients all provide a wide range of preferences and options beyond what can be covered here.  Consult the documentation at the homepages of each client when selecting to get a full view of the capabilities and features of each.  All of the clients mentioned here are available for both Windows and Linux, and different users can choose to use differing clients on the same network without problem.


GAIM is a multi-protocol instant messaging client and is an excellent choice if IM clients will need to connect simultaneously to other services such as IRC, MSN, Yahoo!, or AIM.

To register a new user account with GAIM, open the accounts screen with 'Ctrl-A' and select 'Add'.  You will be presented with a screen similar to Figure 3.1.  Notice that the password field is blank.  Click the 'Register' button. 

Figure 3.1 - GAIM - Add Account

A new window will appear (Figure 3.2) and you will be prompted to confirm the username and enter a password.  Click 'Register' again, and the account will be created.

Note:  GAIM may open two new windows, one for registration and one for login.  Fill out the registration window, as in Figure 3.2, first, before proceeding to login.

Figure3..2 - GAIM - Register

A 'Registration is Successful' message should pop up, after which you will be able to login with your new account.


Spark is a cross-platform Jabber client written in Java, and provided at no-cost by Jive Software.  It offers spell-checking, message broadcasting, and many other business-oriented features.

To add an account to Spark, click the 'Account' link on the login pane.  A window like the one in Figure 3.3 will be displayed.  After filling out the fields, click 'Create Account', and the account will be registered.  You may then login using the login pane.

Figure 3.3 - Spark - Create Account

Spark offers a feature that can be of particular benefit to smaller organizations which may not operate a DNS server.  The IP address of the Jabber server (here, the appliance) can be entered, removing the need for the name to be resolved externally.  To do this, click the 'Advanced' link on the login pane before attempting to register an account or login.  Uncheck the 'Automatically discover host and port' box and enter the IP address of the Jabber appliance the the 'Host' field.  This box is shown in Figure 3.4.  Click OK and continue with registration or login. Still use the server's name when filling out the registration or login boxes, not its IP address.

Figure 3.4 - Spark - Advanced Configuration


Psi is a simple, easy to use Jabber client that excels at handling multiple accounts.  It is lighter weight than the other clients mentioned, and so is an good choice for heavily loaded machines.  It also complies strictly with the Jabber protocols and standards, which makes it widely compatible.

To register a new account on the server using Psi, select 'Account Setup' from the main Psi menu and click 'Add.'  You will be presented with a screen like Figure 3.5.

Figure 3.5 - Psi - Add Account

Make sure that 'Register new account' is checked and then click 'Add.'  A registration screen as shown in Figure 3.6 will be opened.  Notice that the 'Use SSL encryption' checkbox is selected.  Psi does not at this time support StartTLS, which allows encrypted communications to be initiated on the standard port.  If you selected 'Require secure client communications' during setup (the default), you will need to check this box to be able to establish a connection to the server.

Figure 3.6 - Psi - Register

Click 'Register' to make your account.  When the registration has completed, an 'Account Properties' window will open (Figure 3.7).  In the default configuration, Psi will not trust connections using SSL certificates that are self-signed, such as the one made by the Jabber appliance.  Click the 'Connection' tab of the properties window, choose 'Ignore SSL warnings' to allow connections to the server, and then select 'Save.'

Figure 3.7 - Psi - SSL Options

The account setup is complete.  When you login for the first time, an information screen like that in Figure 3.8 will appear.  Enter what details you choose into the fields and click 'Publish.'  Other users on the server will be able to see an retrieve these details.

Figure 3.8 - Psi - Profile

Adding Buddies

No IM server is much use without contacts (buddies), so an overview adding contacts in each client is provided.


To add a buddy using GAIM, bring up the 'Add Buddy' window with the keys Ctrl+B or by selecting Buddies->Add Buddy in the UI.  A window like Figure 3.9 will be opened.  Fill out the details and click 'Add.'  By default, the newly-added contact will need to authorize your request.

Figure 3.9 - GAIM - Add Buddy


To add a buddy with Spark, select Contacts>Add Contact.  A window like Figure 3.10 will be opened.  Fill in the details and click 'Add.'  By default, the newly-added contact will need to authorize your request.

Figure 3.10 - Spark - Add a Buddy


To add a buddy with Psi, select Add Contact->[Account], where [Account] is the name of the service that contains the buddy you wish to add.  A window like that in Figure 3.11 will be opened.  Fill out all the fields, ensuring that the 'Request authorization when adding' checkbox is selected, and click 'Add.'  By default, the user you choose to add will need to authorize your request.

Figure 3.11 - Psi - Add Buddy

Command Line Utilities:

There is an optional utility package available (http://www.redbudcomputer.com/downloads.htm) that provides command-line tools for user management.

For the 'jabberd2_useradd' utility to work as intended, the '<auto-create />' option must be enabled in '/usr/local/etc/jabberd/sm.xml'. This option is commented out by default.

Particularly when performing operations that write to the database--that is, all but the 'jabber2d_userls' command--it is recommended to stop the jabberd2 server first.

For example:

# /etc/rc.d/rc.jabberd stop
# <run command> 
# /etc/rc.d/rc.jabberd start

Command Examples:

jabberd2_userls - Lists users:
  -f      DB file name
  -r      Jabber realm (usually the hostname)
  -w      Show passwords

Example: jabberd2_userls -f /usr/local/var/jabberd/db/authreg.db \
                         -r jabber.domain.com

jabberd2_useradd - Adds a new user:
  -f      DB file name
  -r      Jabber realm (usually the hostname)
  -u      User to add
  -w      New password

Example: jabberd2_useradd -f /usr/local/var/jabberd/db/authreg.db \
                          -r jabber.domain.com \
                          -u newuser \
                          -w password

jabberd2_userdel - Deletes a user:
  -f      DB file name
  -r      Jabber realm (usually the hostname)
  -u      User to delete

Example: jabberd2_userdel -f /usr/local/var/jabberd/db/authreg.db \
                          -r jabber.domain.com \
                          -u olduser

jabberd2_passwd - Changes a user's password:
  -f      DB file name
  -r      Jabber realm (usually the hostname)
  -u      User to change
  -w      New password

Example: jabberd2_passwd -f /usr/local/var/jabberd/db/authreg.db \
                         -r jabber.domain.com \
                         -u user \
                         -w newpw

Additional information and licensing (GPL v2) details for the tools are available in their readme document.

Appendix A - Software Used

BerkeleyDB 4.2.52 Sleepycat Public License
jabberd 2.0s11 GNU Public License
OpenSSH 4.2p1 BSD License
OpenSSL 0.97g OpenSSL (Apache-style) License
Perl 5.8.7 Artistic License
Slackware Linux 10.2 GNU Public License

Appendix B - References

Appendix C - Disclaimer

The information in this document is provided "as is."  No warranty is expressed or implied and no guarantees are made to its accuracy.  Any loss of information, data, or revenue resulting from the use of the information contained in this document is not the responsibility of the author.  Unless specifically stated, the author of this document does not claim to be the original author of any works or products used in this appliance.  All copyrights are the property of their respective owners.

Copyright (C) Thomas E Lackey 2006
Licensed under the Creative Commons Attribution License v2.5