From b9f3572948dee9d479503043e4946d66d4c1655e Mon Sep 17 00:00:00 2001 From: nico wellpott 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(-) 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-54-g00ecf From 68300f2b99e9c3ef6e55eff0df73719d8d12da46 Mon Sep 17 00:00:00 2001 From: nico wellpott Date: Fri, 16 Apr 2021 21:27:33 +0200 Subject: readme: update ejabberd install section --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index d58539e..fc66a0e 100644 --- a/README.md +++ b/README.md @@ -56,10 +56,17 @@ To further protect the integrity of your config the `allow_only` sections define #### ejabberd acl config ```yaml +## ACL section 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 + +## Access Rules +access_rules: + s2s_access: + - deny: spamblacklist + - allow ``` ### automation -- cgit v1.2.3-54-g00ecf From c227b55828d2ecf75f8294b4b72d50000954a0d4 Mon Sep 17 00:00:00 2001 From: nico wellpott Date: Fri, 16 Apr 2021 21:55:01 +0200 Subject: readme: various smaller changes + add automatic ejabberd config reload option to the example --- README.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index fc66a0e..5f7ce49 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ ## bl-imp - the JabberSpam bl(acklist) imp(orter) ### 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. +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 installer (pip). After that the local wrapper `/usr/bin/bl-imp` +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 pip install bl-imp @@ -34,7 +34,7 @@ no outfile assigned 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 +```bashinstaller $ /usr/bin/bl-imp --dry-run outfile selected: None acl: @@ -45,24 +45,24 @@ acl: ``` #### --outfile /path/out.yml -Adding the `outfile` argument while omitting the dry run argument runs the tools silently while doing its thing. +Adding the `outfile` argument while omitting the dry run argument runs the tools silently while doing its thing. ### 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. +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`. To further protect the integrity of your config the +`allow_only` argument restricts the external file to only allow for `acl` rules. #### ejabberd acl config ```yaml -## ACL section +## acl include_config_file: - "/etc/ejabberd/blacklist.yml": <-- the path is completely user configurable - allow_only: <-- these two lines are optional but recommended + "/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 -## Access Rules +## access rules access_rules: s2s_access: - deny: spamblacklist @@ -70,15 +70,14 @@ access_rules: ``` ### automation -The tools is meant to be deployed in an automatic fashion. It is build to operate silently without interrupting the -ejabberd server. +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 run every day at 00:01 to automatically add and remove affected servers from the local -blacklist. +For example the script could be run every day at 00:01 to automatically add/ remove affected servers from the local +blacklist and reload the configuration if the first task finished successfully. ```cron # jabber blacklist update # 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 +1 0 * * * /usr/bin/bl-imp -o /etc/ejabberd/config/blacklist.yml && /usr/bin/ejabberdctl reload_config ``` -- cgit v1.2.3-54-g00ecf From 72120a18304cdee722d042c0ba57f73b556dc08b Mon Sep 17 00:00:00 2001 From: nico wellpott Date: Fri, 16 Apr 2021 22:09:40 +0200 Subject: readme: copiable config * add # to config comments to allow for easy copying --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5f7ce49..57946f4 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ optional arguments: ``` #### without any arguments -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. +Running `bl-imp` without any arguments, cause the tool to update the local cache and etag file. After that the tool will +exit with the exit code `2` followed by the help message to stderr. ```bash no outfile assigned @@ -51,16 +51,16 @@ Adding the `outfile` argument while omitting the dry run argument runs the tools 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`. To further protect the integrity of your config the +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. #### ejabberd acl config ```yaml ## 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 + "/etc/ejabberd/blacklist.yml": # ⟵ the path is completely user configurable + allow_only: # ⟵ the allow_only section is optional but recommended + - acl ## access rules access_rules: -- cgit v1.2.3-54-g00ecf