From e245cb68de0a832ef233a623a2bf392fef782bd0 Mon Sep 17 00:00:00 2001
From: nico <nico@magicbroccoli.de>
Date: Wed, 26 Jun 2019 11:17:56 +0200
Subject: Quality of Life changes

+ add help output if script arguments are invalid
+ add custom exit codes to highlight invalid arguments

* update code comments
* major README rework
---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 61 insertions(+), 18 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 2d2ff33..63dea51 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,74 @@
 ## Blacklist import script
 
-### ejabberd config
-To use this script properly, a separate `yml` file is necessary, as the script will overwrite the file. To further 
-protect the config the `allow_only` sections defines only `acl` rules.
+### installation
+Python 3 virtual environment
+```bash
+virtualenv -p python3
+pip install -r requirements.txt
+```
+
+### usage main.py
+```
+usage: main.py [-h] [-o OUTFILE] [-dr]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -o OUTFILE, --outfile OUTFILE
+                        set path to output file
+  -dr, --dry-run        perform a dry run
+```
+
+#### without any arguments
+Running `main.py` without any arguments, will cause the script to update the local cache and the corresponding `.etag` 
+file. After that the script will output the error and the help message to stderr, before exiting with error code `2` 
+
+```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.
+```bash
+$ /path/blacklist_import: python main.py --dr
+outfile selected: None
+acl:
+  spamblacklist:
+    server:
+      - "a-server.tld"
+      - "b-server.tld"
+```
+
+#### --outfile /path/
+Run without the `--dry-run` argument and a valid outfile, the script will return nothing and do its thing.
+
+##### *ejabberd reload_config*
+The ejabberd instance will be reloaded automatically, but only if changes in the `outfile` occured.
+
+## 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, as the script will overwrite the file. To further protect the integrity of your 
+config the `allow_only` sections defines only `acl` rules.
 ```yaml
   "/etc/ejabberd/blacklist.yml":
     allow_only:
       - acl
 ```
 
-### script configuration
-
+### script itself 
 The script is meant to be used in an automatic fashion.
-Arguments:
 
-- -dr , --dry-run : perform a dry run. `blacklist.txt` and `.etag` are written but no yaml file is overwritten.
-- -o , --outfile filepath : set path to output file
+For example the script could be executed every day at 00:01 to automatically add and remove affected servers from the
+ blacklist file.
 
-The dry-run argument will output the file path, if set, in addition to the contents of the yaml file which would have be produced.
+```cron
+# jabber blacklist update
 
-### script workflow
-1. check if `.etag` file is present
-2. HEAD request
-	2.1 requests etag and `.etag` are equal
-	​	2.1.1 use local `blacklist.txt` file
-	2.2 requests etag and `.etag` are _not_ equal
-	​	2.2.1 request new `blacklist.txt`
-	​	2.2.2 save new `.etag` and `blacklist.txt` file
-3. process `blacklist.txt` and parse output file
+# 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
+```
-- 
cgit v1.2.3-18-g5258