mightyBroccoli
/
bl-imp
mirror of https://github.com/mightyBroccoli/bl-imp
2
1
Fork 0
Code Issues Projects Releases Wiki Activity

ReadMe: update readme to reflect the latest changes

This commit is contained in:
nico 2021-04-14 00:06:22 +02:00
parent c0bd3eba71
commit b9f3572948
Signed by: mightyBroccoli
GPG Key ID: 1F6495B44DABCE6E
1 changed files with 37 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@ -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 utilized. 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 installer (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 the corresponding etag file. After
file. After that the script will output the following error followed by the help message to stderr, before exiting with error code `2` that the tool will 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 ```bash
$ /path/blacklist_import: python main.py --dr $ /usr/bin/bl-imp --dry-run
outfile selected: None outfile selected: None
acl: acl:
spamblacklist: spamblacklist:
@ -50,34 +44,34 @@ 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.
It is required that the tool is the only one editing the defined yml file. It is required 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 file e.g `ejabberd.yml`.
To further protect the integrity of your config the `allow_only` sections defines only `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": include_config_file:
allow_only: "/etc/ejabberd/blacklist.yml": <-- the path is completely user configurable
- acl allow_only: <-- these two lines are optional but recommended
- acl └─ to prevent potentially malicious acls to not incluse anthing but ACL rules
``` ```
### script itself ### automation
The script is meant to be used in an automatic fashion. The tools is meant to be deployed in an automatic fashion. It is build to operate silently without interrupting the
ejabberd server.
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 and remove affected servers from the local
blacklist file. blacklist.
```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
# without virtualenv
1 0 * * * python3 /path/blacklist_import/main.py -o /etc/ejabberd/config/blacklist.yml
``` ```