aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.md35
1 files 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
```