ejabberd-tools/README.md

ejabberd-tools

Repository containing various ejabberd tools.

tools

metrics

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

requirements

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

# mkdir venv
virtualenv -p python3 venv/ -r requirements.txt

ejabberd

It is required to have/ create a user account to operate the tools with. We strongly recommend to use a dedicated user to operate the api and to secure the account with a strong password.

configuration

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.

listen:
  -
    port: 5280
    ip: "127.0.0.1"
    tls: true # optional
    module: ejabberd_http
    request_handlers:
      /api: mod_http_api

acl:
  api:
    user: 
      - "api_user@magicbroccoli.de"
  loopback:
    ip:
      - 127.0.0.0/8
      - ::1/128
      - ::FFFF:127.0.0.1/128

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

ejabberd-metrics.yml

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

We provide a ejabberd-metrics.yml.default file which lists and explains which parameters should be set.

error codes

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

code	potential reason
17	login credential mismatch, potential api permission problem