## 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 a [Prometheus](https://prometheus.io/) and [InfluxDB](https://www.influxdata.com/) client utilizing the metrics class is provided. ### 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. ```bash # 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 ``` #### ejabberd 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. ### configuration #### 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. ```yaml 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 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 user`nobody: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. ```systemd [Unit] Description=ejabberd influxdb exporter [Service] Type=simple # this strongly depends on the ejabberd-metrics.yml permissions User=nobody Group=nogroup ExecStart=/opt/ejabberd-metrics/influx.py Restart=always RestartSec=5s # if the virtualenv is used PATH needs to customized Environment=PATH=/opt/ejabberd-metrics/venv/bin:/usr/bin:/usr/local/bin [Install] WantedBy=multi-user.target ``` 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 | potential reason | | :---: | :---| | 17 | login credential mismatch, potential api permission problem | ### pre-commit framework This project utilizes the [pre-commit](https://pre-commit.com/) 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: ```bash # install the pre-commit hook pre-commit install # to test your staged files manually run pre-commit run ```