114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
## 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 |
|