ejabberd is an XMPP application server powering a good number of instant messaging applications out there.In this post we are going to learn how to install it on a unix based operating system.I will cover ubuntu14.04,but the steps should work on all systems with little or no modifications.
While installing any piece of software ,it is always a good idea to check what the official documentation has to say ,processOne has a good page covering how to install ejabberd.In this tutorial we are going to install from the source code as I find this option most flexible(it is also the most complicated).
Grab yourself a copy of the source code from either github or ejabberd download page.Note that the github version is a development version and it might contain bugs.Use the github version if you want to try the latest introduced features and in production environments use the released standard version from the processOne download page.
git clone git://github.com/processone/ejabberd.git ejabberd
To compile ejabberd you need:
- GNU Make.
- Libexpat 1.95 or higher.
- Libyaml 0.1.4 or higher.
- Erlang/OTP 17.1 or higher.
- OpenSSL 1.0.0 or higher, for STARTTLS, SASL and SSL encryption.
- Zlib 1.2.3 or higher, for Stream Compression support (XEP-0138). Optional.
- PAM library. Optional. For Pluggable Authentication Modules (PAM).
- GNU Iconv 1.8 or higher, for the IRC Transport (mod_irc). Optional. Not needed on systems with GNU Libc.
- ImageMagick’s Convert program. Optional. For CAPTCHA challenges.
Install the dependencies :
sudo apt-get install libexpat1 libexpat1-dev libyaml-0-2 libyaml-dev erlang openssl zlib1g zlib1g-dev libssl-dev libpam0g
The erlang version provided by my ubuntu repo was 16.x.x but 17.1 or higher is required by this ejabberd version we are installing .I had to go to the eerlang download page and downloaded the latest version.
Install the erlang package.Mine is a debian package so I type :
After I download the source code (github or processOne release ) my souce code is stored in
as shown below:
After you have the source code you need to know the install options available to you.Type
This generates a configure script whose options you can show by typing:
From the help output we see a lot of options for our ejabberd installation ,for instance we can specify the location where ejabberd is installed.By default ejabberd installed files are laid out as follows :
/etc/ejabberd/: Configuration directory:
ejabberd.yml: ejabberd configuration file
ejabberdctl.cfg: Configuration file of the administration script
inetrc: Network DNS configuration file for Erlang
ebin/: Erlang binary files (*.beam)
include/: Erlang header files (*.hrl)
priv/: Additional files required at runtime
bin/: Executable programs
lib/: Binary system libraries (*.so)
msgs/: Translation files (*.msgs)
/sbin/ejabberdctl: Administration script (see section ejabberdctl)
/share/doc/ejabberd/: Documentation of ejabberd
/var/lib/ejabberd/: Spool directory:
.erlang.cookie: Erlang cookie file (see section cookie)
acl.DCD, ...: Mnesia database spool files (*.DCD, *.DCL, *.DAT)
/var/log/ejabberd/: Log directory (see section [logfiles]):
ejabberd.log: ejabberd service log
erlang.log: Erlang/OTP system log
You can specify a different location for your installation by specifying a prefix on your configure command :
Another option I find useful is enabling mysql support ,you can do this by typing :
./configure --prefix=/opt/ejabberd-server --enable-mysql
and this causes for the needed modules to be downloaded:
and ejabberd to be compiled,you should see something like this when your make command is done:
to install ejabberd files .Those files are copied to the directory we specified with our configure command in the prefix option .cd to that directory and you see your ejabberd installation files :
Our ejabberdctl program is stored in the sbin directory.To test that our installation works ,we can run it and check the status of our server :
We can see that our node is down.ejabberd is installed but not started yet.Start it by typing
and we can see that it started and running.Here it says that it is ejabberd 0.0 running while we have installed ejabberd 15.11 .This is subject to further investigation ,we ignore it for now.
With our installation working we need to add the admin user and add a few user accounts so that xmpp clients can user them to connect .The processone guide page gives enough info on this but we will reproduce it here just to be complete .
If you go to the /etc/ejabberd directory of your installation you will see a ejabberd.yml file.This is your configuration file.Open the file with your favorite text editor and add another served host.This can be any ip address accessible from the outside or any ping-able domain name.Mine is configured to use a local IP address as follows:
Register an admin user with the command:
./ejabberdctl register admin1 localhost ejabberdPassword ./ejabberdctl register admin1 192.168.1.106 ejabberdPassword
This registers the normal xmpp account user.We register twice because we have two served hosts on the server The 192.168.1.106 account was added because we want access to the web admin from other machines.I left the localhost host here simply because it was there and it doesn’t hurt to keep it there but feel free to comment it out and see what happens.It s a good way to learn.
To give our users admin privileges we modify the ejabberd.yml config file as follows:
Be careful with how you indent your changes in the ejabberd.yml file as errors are hard to debug especially when you are not familiar with yaml.A good example of such an error is this github issue .
We have created two xmpp accounts admin1@localhost and email@example.com on our server.These accounts have bee assigned admin privileges and they can do all kinds of things on the server such as adding and deleting users and much much more such as changing the configurations on the server.
Start the server :
and from your browser ,open the address( it is ofcouse your IP address that you use) :
A window shows up asking you login credentials.Type in your username in the form user@domain (or user@ipAddress) and your password:
Click ok and you are presented the admin interface:
From here you can do all kinds of things ,for example click on Virtual hosts and see the hosts your server is currently serving:
Click on 192.168.1.106 and see settings relating to one host
Click on users and the shown interface allows you to add users to your host:
We have added two accounts to our server host ,firstname.lastname@example.org and email@example.com.These are legitimate accounts on our server and they can actually login from an xmpp client with access to my local network.
If I login from my xmpp clients,the two accounts can exchange messages as shown below :
And from our web admin interface ,we can see them online:
This concludes our ejabberd installation tutorial.What we have done is just a tip of the iceberg and ejabberd can do much much more.Nothing beats trying it yourself and learning from the mistakes you make in the process.If you need to learn more about ejabberd and xmpp in general ,the processone help page and the xmpp standard website are good places to know about.And as always feedback is most welcome.I hope this has been helpful to you and thanks for the visit.
Complete step by step video Course on XMPP and Smack on Android now available. By the Same Author of this Tute.Help spread the news.
We publish both written&video tutorials on XMPP and it’s application on different platforms. Subscribe below to be among the first to be notified.
Liked this tutorial ? Would be great if you helped us back, here is how :
- Share this tutorial with your friends
- Buy or recommend video courses from our online school
You can also join our XMPP Learner Square Group on Facebook to find like minded people!