From f55600ae6df85ce3bb753eb9748f9430e4b1c2d8 Mon Sep 17 00:00:00 2001 From: Justin Warren Date: Tue, 20 Dec 2022 17:24:56 +1100 Subject: [PATCH] Updated README with more detailed config help. Updated sample config file with new options. --- README.md | 107 ++++++++++++++++++++++++++++- etc/sample.fediblockhole.conf.toml | 18 ++--- 2 files changed, 113 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 9f194d8..cbd9bd7 100644 --- a/README.md +++ b/README.md @@ -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 @@ -88,4 +91,102 @@ Once you've configured the tool, run it like this: fediblock_sync.py -c ``` -If you put the config file in `/etc/default/fediblockhole.conf.toml` you don't need to pass the config file path. \ No newline at end of file +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. \ No newline at end of file diff --git a/etc/sample.fediblockhole.conf.toml b/etc/sample.fediblockhole.conf.toml index 9151969..6e669c9 100644 --- a/etc/sample.fediblockhole.conf.toml +++ b/etc/sample.fediblockhole.conf.toml @@ -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 = '' }, - { domain = 'jorts.horse', token = '' }, + # { domain = 'eigenmagic.net', token = '' }, + # { domain = 'jorts.horse', 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 = '' }, + # { domain = 'eigenmagic.net', 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']