83 lines
2.3 KiB
Markdown
83 lines
2.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 [Prometheus](https://prometheus.io/) and [InfluxDB](https://www.influxdata.com/) 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.
|
|
|
|
```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 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.
|
|
|
|
```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 |
|