From b9f3572948dee9d479503043e4946d66d4c1655e Mon Sep 17 00:00:00 2001
From: nico wellpott <nico@magicbroccoli.de>
Date: Wed, 14 Apr 2021 00:06:22 +0200
Subject: ReadMe: update readme to reflect the latest changes

---
 README.md | 80 +++++++++++++++++++++++++++++----------------------------------
 1 file changed, 37 insertions(+), 43 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index abd37d1..d58539e 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,19 @@
-## Blacklist import script
+## bl-imp - the JabberSpam bl(acklist) imp(orter)
 
-### installation
-Python 3 virtual environment
-```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/
+### precursor
+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.
 
-source ./venv/bin/activate
-pip install -r requirements.txt
+### 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
+pip install bl-imp
 ```
 
-### usage main.py
+### `bl-imp` usage
 ```
-usage: main.py [-h] [-o OUTFILE] [-dr]
+usage: bl-imp [-h] [-o OUTFILE] [-dr]
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -29,19 +23,19 @@ optional arguments:
 ```
 
 #### without any arguments
-Running `main.py` without any arguments, will cause the tool to update the local cache and the corresponding `.etag` 
-file. After that the script will output the following error followed by the help message to stderr, before exiting with error code `2` 
+Running `bl-imp` without any arguments, cause the tool to update the local cache and the corresponding etag file. After
+that the tool will exit with the exit code `2` followed by the help message to stderr.
 
 ```bash
 no outfile assigned
-...
 ```
 
 #### dry run
-If `main.py` is executed with `-dr` or `--dry-run` as argument the output would look like this. The script will check 
-the blacklist repository and output everything to stdout without touching any system file besides the local `.etag` file.
+Running `bl-imp` with `-dr` or `--dry-run` as argument will cause the tool to only output the aggregated yaml file to
+stdout. Except the local etag and cache file no file is written to disk.
+
 ```bash
-$ /path/blacklist_import: python main.py --dr
+$ /usr/bin/bl-imp --dry-run
 outfile selected: None
 acl:
   spamblacklist:
@@ -50,34 +44,34 @@ acl:
       - "b-server.tld"
 ```
 
-#### --outfile /path/
-Run without the `--dry-run` argument and a valid outfile, the script will return nothing and do its thing.
+#### --outfile /path/out.yml
+Adding the `outfile` argument while omitting the dry run argument runs the tools  silently while doing its thing.
 
-##### *ejabberd reload_config*
-The ejabberd instance will be reloaded automatically, but only if changes in the `outfile` occurred.
+### ejabberd configuration
+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
-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.
+#### ejabberd acl config
 ```yaml
-  "/etc/ejabberd/blacklist.yml":
-    allow_only:
-      - acl
+include_config_file:
+  "/etc/ejabberd/blacklist.yml":   <-- the path is completely user configurable
+    allow_only:                    <-- these two lines are optional but recommended
+      - acl                         └─ to prevent potentially malicious acls to not incluse anthing but ACL rules
 ```
 
-### script itself 
-The script is meant to be used in an automatic fashion.
+### automation
+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
- blacklist file.
+For example the script could be run every day at 00:01 to automatically add and remove affected servers from the local
+blacklist.
 
 ```cron
 # jabber blacklist update
 
-# with virtualenv enabled
-1 0 * * * /path/blacklist_import/venv/bin/python /path/blacklist_import/main.py -o  /etc/ejabberd/config/blacklist.yml
-
-# without virtualenv
-1 0 * * * python3 /path/blacklist_import/main.py -o  /etc/ejabberd/config/blacklist.yml
+# the outfile here is configured with the shortflag -o instead of the long form
+1 0 * * * /usr/bin/bl-imp -o  /etc/ejabberd/config/blacklist.yml
 ```
-- 
cgit v1.2.3-18-g5258