blob: ac33b009732d9210d82443c370062aea7e718893 (
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
|
## 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 | potential reason |
| :---: | :---|
| 17 | login credential mismatch, potential api permission problem |
|
