A bunch of tools for maintenance a ejabberd server, written in python3 with rest and xmlrpc support: metrics service to fetch statistics from ejabberd to generate metrics for prometheus and influxdb
Go to file
vela-jabber c42b0f8a51 prometheus fix multithreading 2021-04-17 17:58:42 +02:00
contrib/init/linux-systemd clarify documentation 2020-06-10 21:40:01 +02:00
.gitignore yaml config 2020-03-06 12:46:48 +01:00
.gitlab-ci.yml tool configuration 2020-06-27 12:07:09 +02:00
.pre-commit-config.yaml update: pre-commit framework plugins 2020-11-15 23:32:46 +01:00
README.md fix: nodename quotation issue 2020-11-24 23:37:00 +01:00
api.py flake8 fixup 2020-06-29 18:59:16 +02:00
calls.py improve calls 2021-04-17 17:07:42 +02:00
cleanup.py fix datetime in cleanup.py 2020-12-19 14:42:59 +01:00
config.py pathlib config path - short version 2020-09-26 22:09:01 +02:00
ejabberd-metrics.yml.default clarify documentation 2020-06-10 21:40:01 +02:00
influx.py flake8 fixup 2020-06-29 18:59:16 +02:00
metrics.py update: add blabber.im client 2020-11-15 23:34:36 +01:00
prometheus.py prometheus fix multithreading 2021-04-17 17:58:42 +02:00
pyproject.toml tool configuration 2020-06-27 12:07:09 +02:00
requirements.txt pre-commit framework 2020-09-18 21:32:23 +02:00
setup.cfg black flake8 compatability 2020-06-29 01:30:33 +02:00



Repository containing various ejabberd tools.



The metrics class is a tool to gather and aggregate metrics data through the ejabberd rest/ xmlrpc interface. In addition to that a Prometheus and InfluxDB client utilizing the metrics class is provided.


The easiest way to setup a clean Python project environment is to use a virtual environment inside the cloned repository directory. The following bash lines install the python-virtualenv module, create the virtual environment using Python3 and finally install all dependencies listed in the requirements file.

# Debian
apt install python-virtualenv

# Arch
pacman -S python-virtualenv

# create a venv folder inside the cloned repository
mkdir venv
virtualenv -p python3 venv/

source ./venv/bin/activate
pip install -r requirements.txt


To operate the api it is required to provide a user account eligible to issue api commands. We strongly recommend to use a dedicated user to operate the api and to secure this account with a specifically strong password.


ejabberd: api permissions

These configurations options first add the mod_http_api listener. Additionally the user api_user@magicbroccoli.de is added to the acl group, thus enabling him to access the mod_http_api configured in the api_permissions block.

    port: 5280
    ip: ""
    tls: true # optional
    module: ejabberd_http
      /api: mod_http_api

      - "api_user@magicbroccoli.de"
      - ::1/128
      - ::FFFF:

  "api access":
      - mod_http_api
          acl: api
          acl: loopback # optional but recommended to restrict the api access to the local network
      - "*"
      - "!stop"
      - "!start"


The ejabberd-metrics.yml file is the central configuration file which is used by all current and future tools inside this repository.

We provide an ejabberd-metrics.yml.default file, listing all possible and potentially necessary parameters. The final configuration file should be located at /etc/ejabberd-metrics.yml.

systemd service

To properly operate the metrics exporter tools, we created some systemd service templates, to simplify the whole process. If the ejabberd-metrics.yml file is not accessible for the usernobody:nogroup, it is required to update the User and Group definitions inside the service file. If a virtualenv is used, it is required to update the Environment=PATH to include the venv/bin directory created earlier.

Description=ejabberd influxdb exporter


# this strongly depends on the ejabberd-metrics.yml permissions


# if the virtualenv is used PATH needs to customized


Another possible solution would be to edit the ExecStart parameter to include the virtualenv Python intepreter.

error codes

Lookup table for all custom error codes. The potential reasons are sorted by probability of being the root cause.

| code | raised by | cause by | potential reason | | :---: | :---| : --- | :--- | | 17 | calls | api call returned empty | login credential mismatch, potential api permission problem |

pre-commit framework

This project utilizes the pre-commit framework to automate various small hick-ups that tend to happen prior to committing.

To use the framework it is necessary to follow these steps:

# install the pre-commit hook
pre-commit install

# to test your staged files manually run
pre-commit run