This tutorial is outdated. We're currently working on an updated version. In the meantime, for instructions on building a chat app using CometChat, please visit our documentation.
Ejabberd is an XMPP messaging server that is designed to be powerful, scalable and reliable. It is capable of hosting over 2 million users on a single node as well as operating on clusters of servers.
The ejabberd developers created their application to be extremely modular so functionality can be precisely tailored to meet your requirements. This ensures that your server does not run any code that you don’t need to making your ejabberd instance both more secure and more efficient.
In this tutorial, you will learn how to install and configure an ejabberd server on Ubuntu 20.04 that uses free Let’s Encrypt TLS certificates to secure your data.
Prerequisites
You will need the following before you begin this tutorial:
You should have a basic familiarity with Linux system administration. You should be able to move around the file system, edit files and manage services.
An Ubuntu 20.04 server with a sudo enabled, non-root user.
A domain name and several of sub-domains that resolve to your server’s public IP address. The list of sub-domains that you must resolve to your server’s IP is as follows:
<YOURDOMAIN>
pubsub.<YOURDOMAIN>
proxy.<YOURDOMAIN>
conference.<YOURDOMAIN>
upload.<YOURDOMAIN>
The easiest way to achieve this is to use a wildcard A record.
Log into your server as the non-root sudo enabled user to start.
Install ejabberd and its dependencies
First, update your server’s local package list and perform a package update with the following commands:
This will avoid errors when you install ejabberd. Next, install ejabberd from the official Ubuntu repositories:
sudo apt install ejabberd-contrib ejabberd
The package manager started ejabberd at the end of the installation process. We don’t need it running yet so stop it with the following command:
sudo systemctl stop ejabberd
Before you can start configuring ejabberd, you will need to configure the UFW firewall. This will be used for security and also the port forwarding that will be used to get the TLS certificate later in this tutorial.
Configuring UFW
First, open all the ports that ejabberd needs to run with the following commands:
Then enable UFW:
sudo ufw enable
Next, enable IPv4 port forwarding by editing /etc/sysctl.conf. Here, the nano editor is used:
sudo nano /etc/sysctl.conf
Find this line:
#net.ipv4.ip_forward=1
And remove the # at the beginning of the line (uncomment it) so it looks like:
net.ipv4.ip_forward=1
Save and exit the editor.
Then, enable the change with the following command:
sudo sysctl -p
Next, edit /etc/ufw/before.rules and add the following section at the top of the file:
This configuration forwards connections that arrive at the server on port 80 to port 5280 where the ejabberd server will answer them.
Finally, enable this configuration by disabling and enabling UFW:
sudo ufw disable
sudo ufw enable
Configure ejabberd
First, open the main ejabberd configuration file at /etc/ejabberd/ejabberd.yml with a text editor. Set ejabberd to use your domain name by editing the following section:
hosts:
- localhost
Then, replace localhost with your domain name. Here, example.com is used as an example:
hosts:
- "example.com"
Make sure you wrap the domain name in quotes or it will not work.
Next, scroll down and find the following section in the listen section
This section defines how ejabberd works for unencrypted connections on port 5280. Comment out the following three lines as shown here:
The tls: true and protocol_options lines forced this section to use encryption which is not needed here.
The /admin: ejabberd_web_admin line configured the administration interface to be accessible on port 5280 . Since encryption has been disabled this was removed for security purposes.
Next, you need to configure the administration interface to be made available on the encrypted port 5443.
And add /admin: ejabberd_web_admin into the request_handlers: section as shown here:
The last line you need to edit is to enable an admin account. Find this section:
You can now save and exit the editor as you have finished editing this file.
Register a TLS certificate
ejabberd will automatically register all the TLS certificates it needs as long as the Let’s Encrypt registration utility Certbot is installed. The following commands will install Certbot using the Ubuntu Snap utility:
Next, start ejabberd:
sudo systemctl start ejabberd
Then, use the ejabberdctl tool to register all the certificates:
sudo ejabberdctl request_certificate all
Register an admin account
You now need to use the ejabberdctl tool to create the admin user account and set up a password. Use the following command:
sudo ejabberdctl register <USER> <DOMAIN> <PASS>
Using the domain example.com, user admin this gives:
sudo ejabberdctl register admin example.com StronPassWord
Accessing the ejabberd administration interface
You will now be able to log into the administration interface for your ejabberd server. Open your browser and enter the following address:
https://<DOMAIN>:5443/admin
You will be immediately prompted for a username and password to proceed. You need to enter the following details
Username: admin@<DOMAIN>
Password: the password you set.
Here is the authentication box filled in:
After you submit your credentials you will be able to log into your ejabberd administration interface where you can manage your server.
Conclusion
In this tutorial you created an ejabberd XMPP server that is ready for your clients to use and start chatting. ejabberd is an extremely extensible and configurable application, you should refer to the official documentation to learn how to customize your instance.
The official configuration pages are a great place to start.
Elliot Cooper
CometChat
