update readme
This commit is contained in:
parent
28004d3c0b
commit
89c088d4c5
88
README.md
88
README.md
|
|
@ -1,12 +1,23 @@
|
|||
# FediBlockHole
|
||||
# FediBlockHole (Misskey Edition)
|
||||
|
||||
A tool for keeping a Mastodon instance blocklist synchronised with remote lists.
|
||||
A tool for keeping a Misskey instance blocklist synchronised with
|
||||
remote lists. This version of the software has been modified to work
|
||||
with Misskey and its related forks (Sharkey, Firefish, Iceshrimp,
|
||||
etc). The software supports pulling down existing block lists from
|
||||
Mastodon and Misskey-type instances, and supports updating the block
|
||||
list of Misskey-type instances.
|
||||
|
||||
It does NOT support updating block lists of Mastodon instances.
|
||||
|
||||
Original readme follows (modified where appropriate).
|
||||
|
||||
-----------
|
||||
|
||||
The broad design goal for FediBlockHole is to support pulling in a list of
|
||||
blocklists from a set of trusted sources, merge them into a combined blocklist,
|
||||
and then push that merged list to a set of managed instances.
|
||||
|
||||
Mastodon admins can choose who they think maintain quality lists and subscribe
|
||||
Misskey admins can choose who they think maintain quality lists and subscribe
|
||||
to them, helping to distribute the load for maintaining blocklists among a
|
||||
community of people. Control ultimately rests with the admins themselves so they
|
||||
can outsource as much, or as little, of the effort to others as they deem
|
||||
|
|
@ -23,7 +34,7 @@ cost.
|
|||
|
||||
### Blocklist Sources
|
||||
|
||||
- Read domain block lists from other instances via the Mastodon API.
|
||||
- Read domain block lists from other instances via the Mastodon/Misskey API.
|
||||
- Supports both public lists (no auth required) and 'admin' lists requiring
|
||||
authentication to an instance.
|
||||
- Read domain block lists from arbitrary URLs, including local files.
|
||||
|
|
@ -32,7 +43,7 @@ cost.
|
|||
|
||||
### Blocklist Export/Push
|
||||
|
||||
- Push a merged blocklist to a set of Mastodon instances.
|
||||
- Push a merged blocklist to a set of Misskey instances.
|
||||
- Export per-source, unmerged block lists to local files, in CSV format.
|
||||
- Export merged blocklists to local files, in CSV format.
|
||||
- Read block lists from multiple remote instances
|
||||
|
|
@ -50,12 +61,6 @@ cost.
|
|||
|
||||
## Installing
|
||||
|
||||
Installable using `pip`.
|
||||
|
||||
```
|
||||
python3 -m pip install fediblockhole
|
||||
```
|
||||
|
||||
Install from source by cloning the repo, `cd fediblockhole` and run:
|
||||
|
||||
```
|
||||
|
|
@ -70,7 +75,12 @@ authorize the tool to create and update domain blocks with an OAuth token.
|
|||
|
||||
More on authorization by token below.
|
||||
|
||||
### Reading remote instance blocklists
|
||||
### Reading remote instance blocklists (Misskey)
|
||||
|
||||
You will need an admin API token to read the instance block lists of a
|
||||
Misskey instance.
|
||||
|
||||
### Reading remote instance blocklists (Mastodon)
|
||||
|
||||
If a remote instance makes its domain blocks public, you don't need
|
||||
a token to read them.
|
||||
|
|
@ -116,47 +126,7 @@ as explained below.
|
|||
|
||||
### Writing instance blocklists
|
||||
|
||||
To write domain blocks into an instance requires both the `admin:read` and
|
||||
`admin:write:domain_blocks` OAuth scopes.
|
||||
|
||||
The tool needs `admin:read:domain_blocks` scope to read the current list of
|
||||
domain blocks so we update ones that already exist, rather than trying to add
|
||||
all new ones and clutter up the instance.
|
||||
|
||||
`admin:read` access is needed to check if the instance has any accounts that
|
||||
follow accounts on a domain that is about to get `suspend`ed and automatically
|
||||
drop the block severity to `silence` level so people have time to migrate
|
||||
accounts before a full defederation takes effect. Unfortunately, the statistics
|
||||
measure used to learn this information requires `admin:read` scope.
|
||||
|
||||
You can add `admin:read` scope in the application admin screen. Please be aware
|
||||
that this grants full read access to all information in the instance to the
|
||||
application token, so make sure you keep it a secret. At least remove
|
||||
world-readable permission to any config file you put it in, e.g.:
|
||||
|
||||
```
|
||||
chmod o-r <configfile>
|
||||
```
|
||||
|
||||
You can also grant full `admin:write` scope to the application, but if you'd
|
||||
prefer to keep things more tightly secured, limit the scope to
|
||||
`admin:read:domain_blocks`.
|
||||
|
||||
Again, this scope is only available in the application config screen as of
|
||||
Mastodon v4.1.0. If your instance is on an earlier version, you'll need to use
|
||||
SQL to set the scopes in the database and then regenerate the token:
|
||||
|
||||
```
|
||||
UPDATE oauth_applications as app
|
||||
SET scopes = 'admin:read admin:write:domain_blocks'
|
||||
FROM oauth_access_tokens as tok
|
||||
WHERE app.id = tok.application_id
|
||||
AND app.name = '<the_app_name>'
|
||||
;
|
||||
```
|
||||
|
||||
When that's done, FediBlockHole should be able to use its token to authorise
|
||||
adding or updating domain blocks via the API.
|
||||
To write domain blocks into an instance requires an admin API key.
|
||||
|
||||
## Using the tool
|
||||
|
||||
|
|
@ -187,8 +157,8 @@ As the filename suggests, FediBlockHole uses TOML syntax.
|
|||
There are 4 key sections:
|
||||
|
||||
1. `blocklist_urls_sources`: A list of URLs to read blocklists from
|
||||
1. `blocklist_instance_sources`: A list of Mastodon instances to read blocklists from via API
|
||||
1. `blocklist_instance_destinations`: A list of Mastodon instances to write blocklists to via API
|
||||
1. `blocklist_instance_sources`: A list of Mastodon or Misskey instances to read blocklists from via API
|
||||
1. `blocklist_instance_destinations`: A list of Misskey instances to write blocklists to via API
|
||||
1. `allowlist_url_sources`: A list of URLs to read allowlists from
|
||||
|
||||
More detail on configuring the tool is provided below.
|
||||
|
|
@ -259,7 +229,10 @@ All comments are public, by virtue of the public nature of RapidBlock.
|
|||
|
||||
### Instance sources
|
||||
|
||||
The tool can also read domain_blocks from instances directly.
|
||||
The tool can also read domain_blocks from instances directly. Both
|
||||
Mastodon and Misskey instances are supported. Any instance that
|
||||
exposes a fully-compliant Mastodon admin API is also theoretically
|
||||
supported, but untested.
|
||||
|
||||
The configuration is a list of dictionaries of the form:
|
||||
```
|
||||
|
|
@ -293,8 +266,7 @@ The fields `domain` and `token` are required.
|
|||
The fields `max_followed_severity` and `import_fields` are optional.
|
||||
|
||||
The `domain` is the hostname of the instance you want to push to. The `token` is
|
||||
an application token with both `admin:read:domain_blocks` and
|
||||
`admin:write:domain_blocks` authorization.
|
||||
an admin API token.
|
||||
|
||||
The optional `import_fields` setting allows you to restrict which fields are
|
||||
imported from each instance. If you want to import the `reject_reports` settings
|
||||
|
|
|
|||
Loading…
Reference in New Issue