diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 79 |
1 files changed, 61 insertions, 18 deletions
@@ -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 +``` |