From 692d1df2c1b3be45cfff9af993ec52620de0474f Mon Sep 17 00:00:00 2001 From: nico Date: Tue, 9 Jun 2020 19:19:12 +0200 Subject: initial documentation attempt + add install and configuration documentations --- README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/README.md b/README.md index fd4f4e1..0e13bd4 100644 --- a/README.md +++ b/README.md @@ -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. -- cgit v1.2.3-54-g00ecf