Updated README with more detailed config help.

Updated sample config file with new options.
This commit is contained in:
Justin Warren 2022-12-20 17:24:56 +11:00
parent da68b9fc29
commit f55600ae6d
No known key found for this signature in database
2 changed files with 113 additions and 12 deletions

105
README.md
View File

@ -4,8 +4,11 @@ A tool for keeping a Mastodon instance blocklist synchronised with remote lists.
## Features
- Import and export block lists from CSV files.
- Read a block list from a remote instance (if a token is configured)
- Read block lists from multiple remote instances
- Read block lists from multiple URLs, including local files
- Write a unified block list to a local CSV file
- Push unified blocklist updates to multiple remote instances
- Control import and export fields
## Installing
@ -89,3 +92,101 @@ fediblock_sync.py -c <configfile_path>
```
If you put the config file in `/etc/default/fediblockhole.conf.toml` you don't need to pass the config file path.
## More advanced configuration
For a list of possible configuration options, check the `--help` and read the
sample configuration file in `etc/sample.fediblockhole.conf.toml`.
### keep_intermediate
This option tells the tool to save the unmerged blocklists it fetches from
remote instances and URLs into separate files. This is handy for debugging, or
just to have a non-unified set of blocklist files.
Works with the `savedir` setting to control where to save the files.
These are parsed blocklists, not the raw data, and so will be affected by `import_fields`.
The filename is based on the URL or domain used so you can tell where each list came from.
### savedir
Sets where to save intermediate blocklist files. Defaults to `/tmp`.
### no_push_instance
Defaults to False.
When set, the tool won't actually try to push the unified blocklist to any
configured instances.
If you want to see what the tool would try to do, but not actually apply any
updates, use `--dryrun`.
### no_fetch_url
Skip the fetching of blocklists from any URLs that are configured.
### no_fetch_instance
Skip the fetching of blocklists from any remote instances that are configured.
### mergeplan
If two (or more) blocklists define blocks for the same domain, but they're
different, `mergeplan` tells the tool how to resolve the conflict.
`max` is the default. It uses the _highest_ severity block it finds as the one
that should be used in the unified blocklist.
`min` does the opposite. It uses the _lowest_ severity block it finds as the one
to use in the unified blocklist.
A full discussion of severities is beyond the scope of this README, but here is
a quick overview of how it works for this tool.
The severities are:
- **noop**, level 0: This is essentially an 'unblock' but you can include a
comment.
- **silence**, level 1: A silence adds friction to federation with an instance.
- **suspend**, level 2: A full defederation with the instance.
With `mergeplan` set to `max`, _silence_ would take precedence over _noop_, and
_suspend_ would take precedence over both.
With `mergeplan` set to `min`, _silence_ would take precedence over _suspend_,
and _noop_ would take precedence over both.
You would want to use `max` to ensure that you always block with whichever your
harshest fellow admin thinks should happen.
You would want to use `min` to ensure that your blocks do what your most lenient
fellow admin thinks should happen.
### import_fields
`import_fields` controls which fields will be imported from remote
instances and URL blocklists, and which fields are pushed to instances from the
unified blocklist.
The fields `domain` and `severity` are always included, so only define extra
fields, if you want them.
You can't export fields you haven't imported, so `export_fields` should be a
subset of `import_fields`, but you can run the tool multiple times. You could,
for example, include lots of fields for an initial import to build up a
comprehensive list for export, combined with the `--no-push-instances` option so
you don't actually apply the full list to anywhere.
Then you could use a different set of options when importing so you have all the
detail in a file, but only push `public_comment` to instances.
### export_fields
`export_fields` controls which fields will get saved to the unified blocklist
file, if you export one.
The fields `domain` and `severity` are always included, so only define extra
fields, if you want them.

View File

@ -1,19 +1,19 @@
# List of instances to read blocklists from,
# with the Bearer token authorised by the instance
blocklist_instance_sources = [
{ domain = 'eigenmagic.net', token = '<a_token_with_read_auth>' },
{ domain = 'jorts.horse', token = '<a_different_token>' },
# { domain = 'eigenmagic.net', token = '<a_token_with_read_auth>' },
# { domain = 'jorts.horse', token = '<a_different_token>' },
]
# List of URLs to read csv blocklists from
blocklist_url_sources = [
'file:///etc/fediblockhole/blocklist-01.csv',
# 'file:///etc/fediblockhole/blocklist-01.csv',
'https://raw.githubusercontent.com/eigenmagic/fediblockhole/main/samples/demo-blocklist-01.csv',
]
# List of instances to write blocklist to
blocklist_instance_destinations = [
{ domain = 'eigenmagic.net', token = '<read_write_token>' },
# { domain = 'eigenmagic.net', token = '<read_write_token>' },
]
## Store a local copy of the remote blocklists after we fetch them
@ -39,12 +39,12 @@ blocklist_instance_destinations = [
# The 'min' mergeplan will use the lightest severity block found for a domain.
# mergeplan = 'max'
## Set which fields we export
## 'domain' and 'severity' are always exported, these are additional
##
export_fields = ['public_comment']
## Set which fields we import
## 'domain' and 'severity' are always imported, these are additional
##
import_fields = ['public_comment', 'reject_media', 'reject_reports', 'obfuscate']
## Set which fields we export
## 'domain' and 'severity' are always exported, these are additional
##
export_fields = ['public_comment']