ejabberd Installation and Setup
You have several options to install ejabberd:
ejabberdwith Binary Installer
ejabberdwith Operating System Specific Packages
ejabberdfrom Source Code
Once installed, you may want to register users and create admin accounts, if you did not use binary installers:
Installing ejabberd with Binary Installer
Downloading and running the installer
Probably the easiest way to install an
ejabberd instant messaging
server is using the binary installer published by ProcessOne. The
binary installers of released
ejabberd versions are available in the
ejabberd downloads page: ejabberd Downloads.
The binary installer will deploy and configure a full featured
ejabberd server and does not require any extra dependencies. It
includes a stripped down version of Erlang. As such, when using
ejabberd installer, you do not need to install Erlang separately.
In *nix systems, remember to set executable the binary installer before starting it. For example:
chmod +x ejabberd-16.09-linux-x86_64-installer.run ./ejabberd-16.09-linux-x86_64-installer.run
On a *nix system, if you install
ejabberd as root user or if you
install it with deb or rpm manager, it will create two directories in the
root installation directory. Example:
/opt/ejabberd-YY.MMwith YY.MM being the release number will include all binaries, installation logs and configuration example. At uninstallation this directory will be completely removed.
/opt/ejabberdis set to
ejabberduser HOME and will contain all runtime files: effective configuration, database and logs. At uninstallation this directory will NOT be removed.
The installer script support many options, especially for unattended, scripted installation. You can read more on installer options on unattended installation.
ejabberd can be started manually at any time, or automatically by
the operating system at system boot time.
To start and stop
ejabberd manually, use the desktop shortcuts
created by the installer. If the machine doesn’t have a graphical
system, use the scripts ’start’ and ’stop’ in the ’bin’ directory
ejabberd is installed.
On a *nix system, if you want ejabberd to be started as daemon at
boot time, copy
ejabberd.init from the ’bin’ directory to something
/etc/init.d/ejabberd (depending on your distribution). Create a
system user called
ejabberd, give it write access to the directories
logs/, and set that as home; the script will start
the server with that user. Then you can call
start as root to start the server.
When ejabberd is started, the processes that are started in the system
beam.smp, and also
epmd. For more information
epmd consult the section relating to epmd.
ejabberd doesn’t start correctly and a crash dump file is
generated, there was a severe problem. You can try starting
with the script
bin/live.bat in Windows, or with the command
bin/ejabberdctl live in other Operating Systems. This way you see
the error message provided by Erlang and can identify what is exactly
ejabberdctl administration script is included in the
directory. Please refer to the section ejabberdctl for details
ejabberdctl, and configurable options to fine tune the Erlang
Using ejabberd on Microsoft Windows
The Windows installer also adds ejabberd as a system service, and a
shortcut to a debug console for experienced administrators. If you
want ejabberd to be started automatically at boot time, go to the
Windows service settings and set ejabberd to be automatically
started. Note that the Windows service is a feature still in
development, and for example it doesn’t read the file
On Microsoft Windows, the Erlang processes for ejabberd are named
Installing ejabberd with Operating System Specific Packages
Some Operating Systems provide a specific
ejabberd package adapted
to the system architecture and libraries. It usually also checks
dependencies and performs basic configuration tasks like creating the
initial administrator account. Some examples are Debian and
Gentoo. Consult the resources provided by your Operating System for
Usually those packages create a script like
start and stop
ejabberd as a service at boot time.
ProcessOne now provides RPM and DEB all in one packages as well, since ejabberd version 15.06. This is self-sufficient packages also containing a minimal Erlang distribution. It ensures that it does not interfere with your existing Erlang version. This is also a good way to make sure ejabberd will run with the latest Erlang version. You can download the packages from ejabberd Downloads.
Installing ejabberd from Source Code
The canonical form for distribution of
ejabberd stable releases is
the source code package. Compiling
ejabberd from source code is
quite easy in *nix systems, as long as your system have all the
ejabberd on a ‘Unix-like’ operating system, you need:
- GNU Make
- Libexpat 1.95 or higher
- Libyaml 0.1.4 or higher
- Erlang/OTP 17.5 or higher
- OpenSSL 1.0.0 or higher, for STARTTLS, SASL and SSL encryption.
- Zlib 1.2.3 or higher, for Stream Compression support (
- PAM library. Optional. For Pluggable Authentication Modules (PAM). See section pam.
- GNU Iconv 1.8 or higher, for the IRC Transport (mod_irc). Optional. Not needed on systems with GNU Libc. See section mod_irc.
- ImageMagick’s Convert program. Optional. For CAPTCHA challenges. See section captcha.
Downloading ejabberd Source Code
Released versions of
ejabberd are available on ProcessOne
ejabberd downloads page.
Alternatively, the latest development source code can be retrieved from the Git repository using the commands:
git clone git://github.com/processone/ejabberd.git ejabberd cd ejabberd ./autogen.sh
ejabberd execute the commands:
./configure --enable-user=ejabberd --enable-mysql
This tells the configuration to prepare the installed program
to run with a user called
ejabberd, so please create that user
or tell to use another local user.
It isn't recommended to run ejabberd with
Note: To build ejabberd, you will need Internet access, as dependencies will by downloaded depending on the selected options.
The build configuration script allows several options. To get the full list run the command:
Some options that you may be interested in modifying:
-–bindir=/: Specify the path to the user executables (where
-–prefix=/: Specify the path prefix where the files will be copied when running the
-–enable-user[=USER]: Allow this normal system user to execute the ejabberdctl script (see section ejabberdctl), read the configuration files, read and write in the spool directory, read and write in the log directory. The account user and group must exist in the machine before running
make install. This account doesn’t need an explicit HOME directory, because
/var/lib/ejabberd/will be used by default.
-–enable-pam: Enable the PAM authentication method (see section pam).
-–enable-tools: Enable the use of development tools.
-–enable-mysql: Enable MySQL support (see section databases).
-–enable-pgsql: Enable PostgreSQL support (see section databases).
-–enable-sqlite: Enable SQLite support (see section databases).
–-enable-riak: Enable Riak database support (see section databases).
-–enable-redis: Enable Redis support to use for external session storage.
-–enable-zlib: Enable Stream Compression (XEP-0138) using zlib.
-–enable-lager: Use lager Erlang logging tool instead of standard error logger.
-–enable-iconv: Enable iconv support. This is needed for
mod_irc(see section mod_irc).
–-enable-debug: Compile with
–-enable-nif: Replaces some critical Erlang functions with equivalents written in C to improve performance.
–-enable-elixir: Build ejabberd with Elixir extension support.
–-enable-all: Enable all previous options.
--enable-latest-deps: Makes rebar use latest versions of dependences developed alongside
ejabberdinstead of version specified in rebar.config. Should be only used when developing
Here are other available options, that are experimental and not recommended:
–-disable-transient-supervisors: Disable the use of Erlang/OTP supervision for transient processes.
–-enable-hipe: Compile natively with HiPE, not recommended.
ejabberd in the destination directories, run the command:
Note that you probably need administrative privileges in the system to
The files and directories created are, by default:
/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 use the
ejabberdctl command line administration script to
start and stop
ejabberd. If you provided the configure option
–enable-user=USER (see compile), you can execute
with either that system account or root.
prompt> ejabberdctl start prompt> ejabberdctl status The node ejabberd@localhost is started with status: started ejabberd is running in that node prompt> ejabberdctl stop
ejabberd doesn’t start correctly and a crash dump is generated,
there was a severe problem. You can try starting
ejabberd with the
ejabberdctl live to see the error message provided by Erlang
and can identify what is exactly the problem.
Please refer to the section ejabberdctl for details about
ejabberdctl, and configurable options to fine tune the Erlang
If you want ejabberd to be started as daemon at boot time, copy
ejabberd.init to something like
/etc/init.d/ejabberd (depending on
your distribution). Create a system user called
ejabberd; it will be
used by the script to start the server. Then you can call
/etc/inid.d/ejabberd start as root to start the server.
Specific Notes for OSX
Binary installers from ProcessOne does not have Apple Developper signature. If OSX complains when you try to install ejabberd with binary installerd with message: "ejabberd-installer is damaged and can’t be opened" Then you need to disable gatekeeper to be able to install ejabberd:
$ sudo spctl --master-disable <install ejabberd> $ sudo spctl --master-enable
If compiling from sources on OSX, you must configure ejabberd to use custom OpenSSL, Yaml, iconv. The best approach is to use Homebrew to install your dependencies, then exports your custom path to let configure and make be aware of them.
brew install git erlang autoconf automake expat openssl libyaml libiconv sqlite export LDFLAGS="-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib" export CFLAGS="-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include" export CPPFLAGS="-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include" ./configure --enable-mysql make
Specific Notes for BSD
The command to compile
ejabberd in BSD systems is:
Specific Notes for Sun Solaris
You need to have
GNU install, but it isn’t included in Solaris. It
can be easily installed if your Solaris system is set up for
OpenCSW package repository. Make sure
PATH and run:
pkg-get -i coreutils
If that program is called
ginstall, modify the
script to suit your system, for example:
cat Makefile | sed s/install/ginstall/ > Makefile.gi
And finally install
gmake -f Makefile.gi ginstall
Creating an XMPP Account for Administration
ejabberd binary installer prompts you for an admin account, so in that case,
you can probably skip this step.
However, if you use another way of installing ejabberd you may need to create an admin XMPP account.
You need an XMPP account and grant him administrative privileges to
ejabberd Web Admin. Here are the steps to create it:
Register an XMPP account on your
ejabberdserver, for example
email@example.com. There are two ways to register an XMPP account:
ejabberdconfiguration file to give administration rights to the XMPP account you created:
acl: admin: user: - "admin1": "example.org" access: configure: admin: allow
You can grant administrative privileges to many XMPP accounts, and also to accounts in other XMPP servers.
ejabberdto load the new configuration.
Open the Web Admin (usually
http://localhost:5280/admin/) in your favourite browser. Make sure to enter the full JID as username (in this example:
firstname.lastname@example.org). The reason that you also need to enter the suffix is due to
ejabberd’s virtual hosting support. You can manage several XMPP domain on a single instance.
Creating Backend Database
By default, ejabberd uses its own database to store runtime data. In many cases you may need to let ejabberd use an external SQL database. Supported SQL backends are MySQL, PostgreSQL, Sqlite, MSSQL.
When using external database backend, ejabberd does not create schema and tables by itself. You must create the schema before you run ejabberd.
If installing ejabberd from sources, you will find sql script for your backend in the installation directory. By default:
If installing ejabberd from Process-One installer, the init scripts are located in the ejabberd's installation path under