Merge branch 'readme_update'
This commit is contained in:
commit
34fcd52478
86
README.md
86
README.md
|
@ -1,25 +1,19 @@
|
||||||
## Blacklist import script
|
## bl-imp - the JabberSpam bl(acklist) imp(orter)
|
||||||
|
|
||||||
### installation
|
### precursor
|
||||||
Python 3 virtual environment
|
Please be warned that at this point the JabberSpam blacklist is the only list that will be used. It is planed to open up
|
||||||
|
the tool to also import other lists in the future.
|
||||||
|
|
||||||
|
### install
|
||||||
|
The tool can be installed easily via that Python package Index (pip). After that the local wrapper `/usr/bin/bl-imp`
|
||||||
|
can be called to use the module.
|
||||||
```bash
|
```bash
|
||||||
# Debian
|
pip install bl-imp
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### usage main.py
|
### `bl-imp` usage
|
||||||
```
|
```
|
||||||
usage: main.py [-h] [-o OUTFILE] [-dr]
|
usage: bl-imp [-h] [-o OUTFILE] [-dr]
|
||||||
|
|
||||||
optional arguments:
|
optional arguments:
|
||||||
-h, --help show this help message and exit
|
-h, --help show this help message and exit
|
||||||
|
@ -29,19 +23,19 @@ optional arguments:
|
||||||
```
|
```
|
||||||
|
|
||||||
#### without any arguments
|
#### without any arguments
|
||||||
Running `main.py` without any arguments, will cause the tool to update the local cache and the corresponding `.etag`
|
Running `bl-imp` without any arguments, cause the tool to update the local cache and etag file. After that the tool will
|
||||||
file. After that the script will output the following error followed by the help message to stderr, before exiting with error code `2`
|
exit with the exit code `2` followed by the help message to stderr.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
no outfile assigned
|
no outfile assigned
|
||||||
...
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### dry run
|
#### dry run
|
||||||
If `main.py` is executed with `-dr` or `--dry-run` as argument the output would look like this. The script will check
|
Running `bl-imp` with `-dr` or `--dry-run` as argument will cause the tool to only output the aggregated yaml file to
|
||||||
the blacklist repository and output everything to stdout without touching any system file besides the local `.etag` file.
|
stdout. Except the local etag and cache file no file is written to disk.
|
||||||
```bash
|
|
||||||
$ /path/blacklist_import: python main.py --dr
|
```bashinstaller
|
||||||
|
$ /usr/bin/bl-imp --dry-run
|
||||||
outfile selected: None
|
outfile selected: None
|
||||||
acl:
|
acl:
|
||||||
spamblacklist:
|
spamblacklist:
|
||||||
|
@ -50,34 +44,40 @@ acl:
|
||||||
- "b-server.tld"
|
- "b-server.tld"
|
||||||
```
|
```
|
||||||
|
|
||||||
#### --outfile /path/
|
#### --outfile /path/out.yml
|
||||||
Run without the `--dry-run` argument and a valid outfile, the script will return nothing and do its thing.
|
Adding the `outfile` argument while omitting the dry run argument runs the tools silently while doing its thing.
|
||||||
|
|
||||||
##### *ejabberd reload_config*
|
### ejabberd configuration
|
||||||
The ejabberd instance will be reloaded automatically, but only if changes in the `outfile` occurred.
|
To fully utilize the tool some configuration changes are required.
|
||||||
|
Firstly it is necessary that `bl-imp` is the only one editing the defined yml file, because any local change not
|
||||||
|
present in the remote list will be overwritten automatically. Furthermore it is necessary for the file to be separate
|
||||||
|
from the "main" ejabberd configuration e.g `ejabberd.yml`. Lastly to protect the integrity of your config files the
|
||||||
|
`allow_only` argument restricts the external file to only allow for `acl` rules.
|
||||||
|
|
||||||
## configuration
|
#### ejabberd acl config
|
||||||
### ejabberd
|
|
||||||
To use this script properly, you need to add this line to the `ACL` section of your ejabberd instance. Furthermore a
|
|
||||||
separate `yml` file is necessary. To further protect the integrity of your config the `allow_only` sections defines only `acl` rules.
|
|
||||||
```yaml
|
```yaml
|
||||||
"/etc/ejabberd/blacklist.yml":
|
## acl
|
||||||
allow_only:
|
include_config_file:
|
||||||
|
"/etc/ejabberd/blacklist.yml": # ⟵ the path is completely user configurable
|
||||||
|
allow_only: # ⟵ the allow_only section is optional but recommended
|
||||||
- acl
|
- acl
|
||||||
|
|
||||||
|
## access rules
|
||||||
|
access_rules:
|
||||||
|
s2s_access:
|
||||||
|
- deny: spamblacklist
|
||||||
|
- allow
|
||||||
```
|
```
|
||||||
|
|
||||||
### script itself
|
### automation
|
||||||
The script is meant to be used in an automatic fashion.
|
The tool is meant to be used in an automatic fashion. It is build to operate silently without any user interaction.
|
||||||
|
|
||||||
For example the script could be executed every day at 00:01 to automatically add and remove affected servers from the
|
For example the script could be run every day at 00:01 to automatically add/ remove affected servers from the local
|
||||||
blacklist file.
|
blacklist and reload the configuration if the first task finished successfully.
|
||||||
|
|
||||||
```cron
|
```cron
|
||||||
# jabber blacklist update
|
# jabber blacklist update
|
||||||
|
|
||||||
# with virtualenv enabled
|
# the outfile here is configured with the shortflag -o instead of the long form
|
||||||
1 0 * * * /path/blacklist_import/venv/bin/python /path/blacklist_import/main.py -o /etc/ejabberd/config/blacklist.yml
|
1 0 * * * /usr/bin/bl-imp -o /etc/ejabberd/config/blacklist.yml && /usr/bin/ejabberdctl reload_config
|
||||||
|
|
||||||
# without virtualenv
|
|
||||||
1 0 * * * python3 /path/blacklist_import/main.py -o /etc/ejabberd/config/blacklist.yml
|
|
||||||
```
|
```
|
||||||
|
|
Loading…
Reference in New Issue