Updated README with more detailed config help.

Updated sample config file with new options.

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 <configfile_path>
 ```
 
-If you put the config file in `/etc/default/fediblockhole.conf.toml` you don't need to pass the config file 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.

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 = '<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']