ReadMe: update readme to reflect the latest changes
This commit is contained in:
parent
c0bd3eba71
commit
b9f3572948
GPG Key ID:
1F6495B44DABCE6E
80
README.md
80
README.md
|
|
@ -1,25 +1,19 @@
|
|||
## Blacklist import script
|
||||
## bl-imp - the JabberSpam bl(acklist) imp(orter)
|
||||
|
||||
### installation
|
||||
Python 3 virtual environment
|
||||
### 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.
|
||||
|
||||
### 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
|
||||
# Debian
|
||||
apt install python-virtualenv
|
||||
|
||||
# Arch
|
||||
pacman -S python-virtualenv
|
||||
|
||||
# create a venv folder inside the cloned repository
|
||||
mkdir venv
|
||||
virtualenv -p python3 venv/
|
||||
|
||||
source ./venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
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
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue