## 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

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

#### ejabberd
It is required to control a user account eligible to operate the tools with. We strongly recommend to use a dedicated
user to operate the api and to secure this account with a specifically strong password.

### configuration
#### systemd service
To properly operate the metrics exporter tools, we created some systemd 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` paramter to include the virtualenv Python intepreter.

#### 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 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 |