docs.ejabberd.im

ejabberd Installation and Setup

You have several options to install ejabberd:

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 ProcessOne 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.MM with YY.MM being the release number will include all binaries, installation logs and configuration example. At uninstallation this directory will be completely removed.
  • /opt/ejabberd is set to ejabberd user 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.

Starting ejabberd

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 where 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 like /etc/init.d/ejabberd (depending on your distribution). Create a system user called ejabberd, give it write access to the directories database/ and logs/, and set that as home; the script will start the server with that user. Then you can call /etc/inid.d/ejabberd start as root to start the server.

When ejabberd is started, the processes that are started in the system are beam or beam.smp, and also epmd. For more information regarding epmd consult the section relating to epmd.

If ejabberd doesn’t start correctly and a crash dump file is generated, there was a severe problem. You can try starting ejabberd 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 the problem.

The ejabberdctl administration script is included in the bin directory. Please refer to the section ejabberdctl for details about ejabberdctl, and configurable options to fine tune the Erlang runtime system.

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 ejabberdctl.cfg.

On Microsoft Windows, the Erlang processes for ejabberd are named erl.exe and epmd.exe.

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 more information.

Usually those packages create a script like /etc/init.d/ejabberd to 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 dependencies.

Requirements

To compile ejabberd on a ‘Unix-like’ operating system, you need:

  • GNU Make
  • GCC
  • 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 (XEP-0138). Optional.
  • 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

Compile

To compile 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 root user.

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:

./configure --help

Configure options

Some options that you may be interested in modifying:

  • -–bindir=/: Specify the path to the user executables (where epmd and iex are available).

  • -–prefix=/: Specify the path prefix where the files will be copied when running the make install command.

  • -–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 +debug_info enabled.

  • –-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 ejabberd instead of version specified in rebar.config. Should be only used when developing ejabberd.

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.

Install

To install ejabberd in the destination directories, run the command:

make install

Note that you probably need administrative privileges in the system to install ejabberd.

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
  • /lib/ejabberd/:

    • 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

Start

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 ejabberdctl with either that system account or root.

Usage example:

prompt> ejabberdctl start

prompt> ejabberdctl status
The node ejabberd@localhost is started with status: started
ejabberd is running in that node

prompt> ejabberdctl stop

If ejabberd doesn’t start correctly and a crash dump is generated, there was a severe problem. You can try starting ejabberd with the command 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 runtime system.

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

Specific Notes for OSX (Yosemite, El Capitan, Sierra)

On OS X, you need to tell ejabberd to use custom OpenSSL, Yaml, iconv for the build. The best approach is to use Homebrew to install your dependencies:

brew install git erlang autoconf automake expat openssl libyaml libiconv sqlite

Here is an example command to build ejabberd with brew-installed dependencies:

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

Note: Reference to custom OpenSSL needs at the moment to be passed to make command. This is because make command download, configure and build dependencies. The reference is also needed in that context.

Please, make sure that for OSX El Capitan you are aware of rootless feature and have read Homebrew documentation no that topic: El Capitan & Homebrew

Specific Notes for BSD

The command to compile ejabberd in BSD systems is:

gmake

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 /opt/csw/bin is in your PATH and run:

pkg-get -i coreutils

If that program is called ginstall, modify the ejabberd Makefile script to suit your system, for example:

cat Makefile | sed s/install/ginstall/ > Makefile.gi

And finally install ejabberd with:

gmake -f Makefile.gi ginstall

Post-install Operations

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 enter the ejabberd Web Admin. Here are the steps to create it:

  1. Register an XMPP account on your ejabberd server, for example admin1@example.org. There are two ways to register an XMPP account:

    1. Using ejabberdctl (see section ejabberdctl):

      ejabberdctl register admin1 example.org FgT5bk3
      
    2. Using an XMPP client and In-Band Registration (see section mod_register).

  2. Edit the ejabberd configuration 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.

  3. Restart ejabberd to load the new configuration.

  4. 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: admin1@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: /usr/local/lib/ejabberd/priv/sql

  • If installing ejabberd from Process-One installer, the init scripts are located in the ejabberd's installation path under <base>/lib/ejabberd*/priv/sql

See ejabberd SQL Database Schema for details on database schemas. See Step-by-step Databases Configuration Guides for detailed setup instructions.