blob: fe0c0f31ed11e491af9f5a74deb4db8b44100528 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
## 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
# create a venv folder inside the cloned repository
mkdir venv
virtualenv -p python3 venv/
source ./venv/bin/activate
pip install -r requirements.txt
```
#### ejabberd
To operate the api it is required to provide a user account eligible to issue api commands. We strongly recommend to use
a dedicated user to operate the api and to secure this account with a specifically strong password.
### configuration
#### 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 an `ejabberd-metrics.yml.default` file, listing all possible and potentially necessary parameters. The final
configuration file should be located at `/etc/ejabberd-metrics.yml`.
#### systemd service
To properly operate the metrics exporter tools, we created some systemd service 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` parameter to include the virtualenv Python intepreter.
### error codes
Lookup table for all custom error codes.
The potential reasons are sorted by probability of being the root cause.
| code | raised by | cause by | potential reason |
| :---: | :---| : --- | :--- |
| 17 | calls | api call returned empty | login credential mismatch, potential api permission problem |
### pre-commit framework
This project utilizes the [pre-commit](https://pre-commit.com/) framework to automate various small hick-ups that tend
to happen prior to committing.
To use the framework it is necessary to follow these steps:
```bash
# install the pre-commit hook
pre-commit install
# to test your staged files manually run
pre-commit run
```
|
