Skip to content

Add More Modules

ejabberd-modules

ejabberd starts automatically modules installed in .ejabberd-modules, in addition to all the modules included with ejabberd. There are API commands to compile, install, upgrade and uninstall those additional modules.

Info

The exact path to the ejabberd-modules directory in your ejabberd installation may be:

That path can be modified using the variable CONTRIB_MODULES_PATH in the ejabberdctl.cfg configuration file.

To get new modules in ejabberd-modules:

ejabberd-contrib

ejabberd-contrib is a git repository that hosts a collection of contributed modules for ejabberd written in Erlang/Elixir. Check the ejabberd-contrib GitHub page.

Furthermore, in the extra directory of that repository there are references to other modules hosted in other git repositories.

First of all, let's get/update the modules source code:

ejabberdctl modules_update_specs

Modules Management

Once you have placed the modules source code in ejabberd-modules, you can:

List Modules

Get a list of all the modules available to install:

ejabberdctl modules_available

...
mod_cron        Execute scheduled commands
mod_default_contacts    Auto-add roster contacts on registration
mod_default_rooms       Auto-bookmark rooms on registration
mod_deny_omemo  Prevent OMEMO sessions from being established
mod_ecaptcha    Generate CAPTCHAs using ecaptcha
...

What modules are currently installed:

ejabberdctl modules_installed

Install Module

Let’s install a module:

ejabberdctl module_install mod_cron

Module mod_cron has been installed and started.
It's configured in the file:
  /home/ejabberd/.ejabberd-modules/mod_cron/conf/mod_cron.yml
Configure the module in that file, or remove it
and configure in your main ejabberd.yml

That command performs several tasks:

  • downloads any Erlang/Elixir dependencies specified in the modules's rebar.config file
  • compiles the module and its dependencies (if not yet already compiled)
  • installs it (inside ejabberd-modules)
  • copies the default module configuration file (if any)
  • and starts the module (if there was a default configuration file

As a result, now .ejabberd-modules contains a new directory mod_cron/ with the binary *.beam files and the default module configuration.

The default module configuration file, if it exists, will be read by ejabberd when it starts. If you prefer to keep all the configuration in your main ejabberd.yml file, move the content of that file, but remember that the file will be overwritten if you install or upgrade the module.

Uninstall Module

And finally, you can uninstall the module:

ejabberdctl module_uninstall mod_cron

By the way, you can upgrade the module, which essentially uninstalls and installs the same module with one single command call:

ejabberdctl module_upgrade mod_cron

Dependencies in container

When a module in ejabberd-modules depends on an Erlang or Elixir library, it is defined in the rebar.config file. To download those dependencies during module installation, either git or mix is required, but none of them are available in the ejabberd or the ecs container images. Consequently, the module installation will fail. The solution is quite simple: install git or mix.

For example, let's start an ejabberd container and try to install a module with dependencies:

podman run --name ejabberd -d -p 5222:5222 -p 5280:5280 ghcr.io/processone/ejabberd

podman exec ejabberd ejabberdctl module_install mod_ecaptcha

An error message like this will appear:

Fetching dependency ecaptcha: /bin/sh: git: not found
/bin/sh: cd: line 1: can't cd to ecaptcha: No such file or directory
/bin/sh: git: not found
Module mod_ecaptcha has been installed and started.
It's configured in the file:
  /opt/ejabberd/.ejabberd-modules/mod_ecaptcha/conf/mod_ecaptcha.yml
Configure the module in that file, or remove it
and configure in your main ejabberd.yml

In order to download modules dependencies, first of all install git in the container:

podman exec --user root ejabberd apk add git

Now remove the module deps/ folder and install again:

podman exec ejabberd rm -rf /opt/ejabberd/.ejabberd-modules/sources/ejabberd-contrib/mod_ecaptcha/deps/

podman exec ejabberd ejabberdctl module_upgrade mod_ecaptcha

This time dependencies will be downloaded, compiled and installed:

Fetching dependency ecaptcha: Cloning into 'ecaptcha'...
Module mod_ecaptcha has been installed and started.
It's configured in the file:
  /opt/ejabberd/.ejabberd-modules/mod_ecaptcha/conf/mod_ecaptcha.yml
Configure the module in that file, or remove it
and configure in your main ejabberd.yml