aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.md73
1 files changed, 73 insertions, 0 deletions
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.