Ejabberd comes with various default settings that make it easy to get started. We can install Ejabberd and start using it as soon as installation completes. This works when we are testing our setup, but when we need a production server, we need to make a number of changes to the default installation. Ejabberd provides a central configuration file through which we can easily configure our XMPP installation.
This recipe covers the basic configuration of the Ejabberd server.
Make sure that you have installed the Ejabberd server.
You will need access to a root account or an account with sudo privileges.
Ejabberd configuration files are located under the conf directory in the Ejabberd installation. On the Ubuntu server, it should be /opt/ejabberd-version/conf.
Follow these steps to configure the Ejabberd installation:
- Open the
ejabberd.ymlfile. It contains configuration settings in the YML format. - Let us start by setting the domain for our XMPP service. This is located under the
SERVED HOSTNAMESsection in the configuration file. The default setting uses the server hostname as a host for the XMPP service. - Add a fully qualified domain name under the
hostssection. You can choose to keep the default host entry or remove it:
- Next, you may want to change the default ports for XMPP connections. Search for the
LISTENING PORTSsection inejabberd.ymland change the respective ports. I will use the default port configuration. The following is the configuration snippet listingport 5222:
- The
LISTENING PORTSsection contains different port configurations, each serving a separate service. Three of them are enabled by default and serve a client to server connection (5222), server to server connection (5269), and HTTP module for admin console andhttp_bindservice (5280). - The same section contains the parameter named
certfile, which specifies the SSL certificate file to be used while creating client connections. The default settings point to a certificate created by the Ejabberd installation process. You can change it to your own signed certificate. - Also note the shaper and access settings. These settings specify the connection throttling and access control settings used for the client to server connections respectively.
- At the end of the
LISTENING PORTSsection, there is a configuration forBOSH(port5280) connections, as well as the web admin panel. This section also enables web socket connections with theejabberd_http_wsmodule. - Under the
AUTHENTICATIONsection, you can configure the authentication mechanism to be used. By default, Ejabberd usesinternalauthentication but it can be set to useexternalscripts, system-level authentication, external databases, or even a centralized LDAP service. The following is the list of all supported options:
- Default
internalauthentication works well enough and we will proceed with it. If you are planning to use a different authentication mechanism, make sure that you comment outinternalauthentication. - You can also enable anonymous login support, where clients can open an XMPP connection without a username and password. Simply uncomment the respective settings from
Anonymous login support:
- Next, under the
DATABASE SETUPsection, you can set Ejabberd to use an external database system. Ejabberd supports all leading relational database systems, includingSQLite. The following is the list of all supported database systems:
- The default database settings use an inbuilt database server known as Mnesia. It provides in-memory and disk-based storage and can be easily replicated across Ejaberd nodes. Mnesia works well even for very busy XMPP operations.
- To define an admin user, search for the
ACCESS CONTROL LISTSsection and add your desired username and hostname under the admin users list:
This same section includes a list of blocked users.
You can also define your own access control lists, which can be used to restrict permissions to specific hostnames or users. The Access Rules section define the rules applicable to listed ACLs.
- Finally, under the
modulessection, you can configure the modules to be used by Ejabberd. Modules are plugins to extend the functionality of the Ejabberd server. Comment out the modules that you are not planning to use. You can also enable or disable any module in runtime from the web admin panel. The following is the partial list of modules:
Each module is named after respective XEPs (XMPP extensions). You can get details of the functionality of any module by looking for the related XEP. Also check the Ejabberd documentation to find out the dependencies between modules.
- Once you are done with all the configuration, you can restart the Ejabberd server with
ejabberdctl restartor reload configuration changes with theejabberdctl reload_configcommand:$ sudo bin/ejabberdctl reload_config
Most of the core settings of Ejabberd are controlled through the configuration file, ejabberd.yml. Alternatively, you can change settings with the ejabberdctl command, but those settings will not persist after restart. If you need the settings to be permanent, change them in the configuration file. You can always reload the configuration file changes without restarting the server.
While editing the configuration file, make sure that you follow the indentation and spacing as shown in examples. Ejabberd configuration follows the YML format and any change in spacing will leave that setting undefined. The good news is that the latest version of Ejabberd will prompt you about any mistakes in configuration.
There's another file named ejabberdctl.cfg that contains Erlang runtime settings. You may need to update those parameters while performance tuning the Ejabberd server.
The Ejabberd server is highly extensible and customizable thanks to its modular architecture. Most Ejabberd features are implemented as external modules. Modules are pluggable components that can be used to extend core functionality. These modules can be enabled or disabled as per requirements and do not affect the core functionality. Ejabberd modules are written in either Erlang or Elixir.
Ejabberd modules work with the hook mechanism implemented in the Ejabberd core. Hooks are nothing but simple events such as message received, user logged in, and connection time out. You can get a full list of supported hooks in the Ejabberd documentation, although it may not be a complete list. Each hook gets its own handler chain, with each handler assigned with a priority number. When you enable a module, it registers a given handler with a respective hook and a position or priority in the handler chain. When a hook is triggered by an event, it executes each handler in a chain, one after another. Additionally, a handler function may request to stop processing hooks and not to execute any further handlers.
The Ejabberd administrative command ejabberdctl provides an option to search for and install external modules. Ejabberd takes care of downloading the module, compiling, and installing it. You can even write your own module and add it to the local repository for installation. Check Ejabberd's developer documents for more details on module development.
- List of XMPP extensions at http://xmpp.org/xmpp-protocols/xmpp-extensions/
- Ejabberd document at link - https://www.process-one.net/docs/ejabberd/guide_en.html
- Ejabberd developer documentation at http://docs.ejabberd.im/developer/modules/
- Ejabberd hooks at http://docs.ejabberd.im/developer/hooks/