initial documentation attempt

+ add install and configuration documentations
This commit is contained in:
nico 2020-06-09 19:19:12 +02:00
parent 5cf6889799
commit 692d1df2c1
Signed by: mightyBroccoli
GPG Key ID: EA7C31AAB1BDC1A2
1 changed files with 73 additions and 0 deletions

View File

@ -1,4 +1,77 @@
## 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.