diff options
Diffstat (limited to 'docs/admin')
| -rw-r--r-- | docs/admin/domain_blocks.md | 73 | ||||
| -rw-r--r-- | docs/admin/federation_modes.md | 62 | ||||
| -rw-r--r-- | docs/admin/settings.md | 88 |
3 files changed, 201 insertions, 22 deletions
diff --git a/docs/admin/domain_blocks.md b/docs/admin/domain_blocks.md new file mode 100644 index 000000000..76f11d8a5 --- /dev/null +++ b/docs/admin/domain_blocks.md @@ -0,0 +1,73 @@ +# Domain Blocks + +GoToSocial supports 'blocking'/'suspending' domains that you don't want your instance to federate with. In our documentation, the two terms 'block' and 'suspend' are used interchangeably with regard to domains, because they mean the same thing: preventing your instance and the instance running on the target domain from communicating with one another, effectively cutting off federation between the two instances. + +You can view, create, and remove domain blocks and domain allows using the [instance admin panel](./settings.md#federation). + +This document focuses on what domain blocks actually *do* and what side effects are processed when you create a new domain block. + +## How does a domain block work + +A domain block works by doing two things: + +Firstly, it instructs your instance to refuse any requests made to it from the target domain: + +- All incoming requests from the blocked domain to your instance will be responded to with HTTP status code `403 Forbidden`. +- This makes it impossible for an account on the target domain to interact with an account on your instance, or any statuses created by that account, since your instance will simply refuse to process the request. +- This also extends to GET requests: your instance will no longer serve an ActivityPub response to a request by a blocked instance to fetch, say, an account's bio, or pinned statuses, etc. +- Boosts of statuses from accounts on your instance should also not be visible to accounts on blocked instances, since those instances will not be able to fetch the content of the status that has been boosted. + +Secondly, a domain block instructs your instance to no longer make any requests to the target instance. This means: + +- Your instance will not deliver any messages to an instance on a blocked domain. +- Nor will it fetch statuses, accounts, media, or emojis from that instance. + +## Safety concerns + +### Block evasion + +Domain blocking is not airtight. GoToSocial *can* ensure that it will neither serve requests from nor make requests to instances on blocked domains. Unfortunately it *cannot* guarantee that accounts on your instance will never be visible in any way to users with accounts on blocked instances. Consider the following circumstances, all of which represent a form of [block evasion](https://en.wikipedia.org/wiki/Block_(Internet)#Evasion): + +- You've domain blocked `blocked.instance.org`. A user on `blocked.instance.org` makes an account on `not-blocked.domain`, so that they can use their new account to interact with your posts or send messages to you. They may be upfront about who they are, or they may use a false identity. +- You've domain blocked `blocked.instance.org`. A user on `not-blocked.domain` screenshots a post of yours and sends it to someone on `blocked.instance.org`. +- You've domain blocked `blocked.instance.org`. A user on `blocked.instance.org` visits the web view of your profile to read your public posts. +- You've domain blocked `blocked.instance.org`. You have RSS enabled for your profile. A user from `blocked.instance.org` subscribes to your RSS feed to read your public posts. + +In the above cases, `blocked.instance.org` remains blocked, but users from that instance may still have other ways of seeing your posts and possibly reaching you. + +With this in mind, you should only ever treat domain blocking as *one layer* of your privacy onion. That is, domain blocking should be deployed alongside other layers in order to achieve a level of privacy that you are comfortable with. This ought to include things like not posting sensitive information publicly, not accidentally doxxing yourself in photos, etc. + +### Block announce bots + +Unfortunately, the Fediverse has its share of trolls, many of whom see domain blocking as an adversary to be defeated. To achieve this, they often target instances which use domain blocks to protect users. + +As such, there are bots on the Fediverse which scrape instance domain blocks and announce any discovered blocks to the followers of the bot, opening the admin of the blocking instance up to harassment. These bots use the `api/v1/instance/peers?filter=suspended` endpoint of GoToSocial instances to gather domain block information. + +By default, GoToSocial does not expose this endpoint publicly, so your instance will be safe from such scraping. However, if you set `instance-expose-suspended` to `true` in your config.yaml file, you may find that this endpoint gets scraped occasionally, and you may see your blocks being announced by troll bots. + +## What are the side effects of creating a domain block + +When you create a new domain block (or resubmit an existing domain block), your instance will process side effects for the block. These side effects are: + +1. Mark all accounts stored in your database from the target domain as suspended, and remove most information (bio, display name, fields, etc) from each account marked this way. +2. Clear all mutual and one-way relationships between local accounts and suspended accounts (followed, following, follow requests, bookmarks, etc). +3. Delete all statuses from suspended accounts. +4. Delete all media from suspended accounts and their statuses, including media attachments, avatars, headers, and emojis. + +!!! danger + Currently, most of the above side effects are **irreversible**. If you unblock a domain after blocking it, all accounts on that domain will be marked as no longer suspended, and you will be able to interact with them again, but all relationships will still be wiped out, and all statuses and media will be gone. + + Think carefully before blocking a domain. + +## Blocking a domain and all subdomains + +When you add a new domain block, GoToSocial will also block all subdomains of the blocked domain. This allows you to block specific subdomains, if you wish, or to block a domain more generally if you don't trust the domain owner. + +Some examples: + +1. You block `example.org`. This blocks the following domains (not exhaustive): `example.org`, `subdomain.example.org`, `another-subdomain.example.org`, `sub.sub.sub.domain.example.org`. +2. You block `baddies.example.org`. This blocks the following domains (not exhaustive): `baddies.example.org`, `really-bad.baddies.example.org`. However the following domains are not blocked (not exhaustive): `example.org`, `subdomain.example.org`, `not-baddies.example.org`. + +A more practical example: + +Some absolute jabroni owns the domain `fossbros-anonymous.io`. Not only do they run a Mastodon instance at `mastodon.fossbros-anonymous.io`, they also have a GoToSocial instance at `gts.fossbros-anonymous.io`, and an Akkoma instance at `akko.fossbros-anonymous.io`. You want to block all of these instances at once (and any future instances they might create at, say, `pl.fossbros-anonymous.io`, etc). You can do this by simply creating a domain block for `fossbros-anonymous.io`. None of the instances at subdomains will be able to communicate with your instance. Yeet! diff --git a/docs/admin/federation_modes.md b/docs/admin/federation_modes.md new file mode 100644 index 000000000..8313d8af2 --- /dev/null +++ b/docs/admin/federation_modes.md @@ -0,0 +1,62 @@ +# Federation Modes + +GoToSocial currently offers both 'blocklist' and 'allowlist' federation modes, which can be set using the `instance-federation-mode` setting in the config.yaml, or using the `GTS_INSTANCE_FEDERATION_MODE` environment variable. These are described below. + +## Blocklist federation mode (default) + +When `instance-federation-mode` is set to `blocklist`, your instance will federate openly with other instances, without restriction, with the exception of instances you have explicitly created domain blocks for via the settings panel. + +When your instance receives a new request from an instance that is not blocked via a domain block entry, it will serve the request if the request is valid, and if the requester is permitted to view the resource that's being requested (taking account of status visibility, and any user-level blocks). + +When your instance encounters a mention or an announce of a status or account it hasn't seen before, it will go fetch the resource if the domain of the resource is not blocked via a domain block entry. + +!!! info + Blocklist federation mode is the default federation mode for GoToSocial. It's also the default for most other ActivityPub server implementations. + +## Allowlist federation mode + +!!! warning + Allowlist federation mode is still considered "experimental" while we work out how well it actually works in practice. It should do what it says on the box, but it may cause bugs or edge cases to appear elsewhere, we're not sure yet! + +When `instance-federation-mode` is set to `allowlist`, your instance will federate only with instances for which an explicit allow has been created via the settings panel, and will restrict access by any instances for which an allow has not been created. + +When your instance receives a new request from an instance that is not explicitly allowed via a domain allow entry, it will refuse to serve the request. If the request comes from a domain that is on the allowlist, your instance will serve the request (taking account of status visibility, and any user-level blocks). + +When your instance encounters a mention or an announce of a status or account it hasn't seen before, it will only go fetch the resource if the domain of the resource is explicitly allowed via a domain allow entry. + +!!! tip + Allowlist federation mode is useful in cases where you want to federate only with select 'trusted' instances. However, this comes at the cost of hampering discovery. Under blocklist federation mode, you will organically encounter posts and accounts from instances you were not yet aware of, via boosts and replies, but in allowlist federation mode no such serendipity will occur. + + As such, it is recommended that you *either* start with blocklist federation mode and switch over to allowlist federation later on once you've established which other instances you 'like', *or* you start with allowlist federation mode, and have an allowlist populated and ready to import after first booting up your instance, in order to 'bootstrap' it. + +## Combining blocks and allows + +It is possible to both block and allow the same domain, and the effect of combining these two things depends on which federation mode your instance is currently using. + + + +### In blocklist mode + +As the chart shows, in blocklist mode (the left-hand part of the diagram), an explicit domain allow can be used to override a domain block. + +This is useful in cases where you are importing a blocklist from someone else, but the imported blocklist contains some instances you would actually prefer not to block. To avoid blocking those instances, you can create explicit domain allows for those instances first. Then, when you import the block list, the explicitly allowed domains will not be blocked, and the side effects of creating a block (deleting statuses, media, relationships etc) will not be processed. + +If you later remove an explicit allow for a domain that also has a block, the instance will become blocked, and side effects of block creation will be processed. + +Conversely, if you add an explicit allow for a domain that was blocked, the side effects of block *deletion* will be processed. + +### In allowlist mode + +As the chart shows, in allowlist mode (the right-hand part of the diagram) an explicit domain block trumps an explicit domain allow. The following two things must be true in order for an instance to be allowed through, when running in allowlist mode: + +1. An explicit domain block **does not exist** for the instance. +2. An explicit domain allow **does exist** for the instance. + +If either of the above conditions are not met, the request will be denied. + +!!! danger + Combining blocks and allows is a tricky business! + + When importing lists of allows and blocks, you should always review the list manually to make sure that you do not inadvertently block a domain that you would prefer not to block, since this can have **very annoying side effects** like removing follows/following, statuses, etc. + + When in doubt, always add an explicit allow first as an insurance policy! diff --git a/docs/admin/settings.md b/docs/admin/settings.md index c30806331..344a97473 100644 --- a/docs/admin/settings.md +++ b/docs/admin/settings.md @@ -1,57 +1,101 @@ -# Admin Settings +# Admin Settings Panel -The GoToSocial Settings interface uses the [admin api routes](https://docs.gotosocial.org/en/latest/api/swagger/#operations-tag-admin) to manage your instance. It's combined with the [User settings](../user_guide/settings.md) and uses the same OAUTH mechanism as normal clients (with scope: admin). +The GoToSocial admin settings panel uses the [admin API](https://docs.gotosocial.org/en/latest/api/swagger/#operations-tag-admin) to manage your instance. It's combined with the [user settings panel](../user_guide/settings.md) and uses the same OAuth mechanism as normal clients (with scope: admin). -## Account permissions -To use the Admin API your account has to be promoted as such: -``` +## Setting admin account permissions and logging in + +To use the admin settings panel, your account has to be promoted to admin: + +```bash ./gotosocial --config-path ./config.yaml admin account promote --username YOUR_USERNAME ``` -After this, you can enter your instance domain in the login field (auto-filled if you run GoToSocial on the same domain), and login like you would with any other client. +In order for the promotion to 'take', you may need to restart your instance after running the command. +After this, you can navigate to `https://[your-instance-name.org]/settings`, enter your domain in the login field, and login like you would with any other client. You should now see the admin settings. -## Instance Settings - +## Moderation + +Instance moderation settings. -Here you can set various metadata for your instance, like the displayed name, thumbnail image, description texts (HTML), and contact username and email. +### Reports + + + +The reports section shows a list of reports, originating from your local users, or remote instances (shown anonymously as just the name of the instance, without specific username). -## Actions -You can use media cleanup to remove remote media older than the specified number of days. This also removes unused headers and avatars. +Clicking a report shows if it was resolved (with the reasoning if available), more information, and a list of reported toots if selected by the reporting user. You can also use this view to mark a report as resolved, and fill in a comment. Whatever comment you enter here will be visible to the user that created the report, if that user is from your instance. + +Clicking on the username of the reported account opens that account in the 'Accounts' view, allowing you to perform moderation actions on it. + +### Accounts + +You can use this section to search for an account and perform moderation actions on it. + +### Federation -## Federation  -In the federation section you can influence which instances you federate with, through adding domain blocks. You can enter a domain to suspend in the search field, which will filter the list to show you if you already have a block for it. Clicking 'suspend' gives you a form to add a public and/or private comment, and submit to add the block. Adding a suspension will suspend all the currently known accounts on the instance, and prevent any new interactions with any user on the blocked instance. +In the federation section you can create, delete, and review explicit domain blocks and domain allows. + +For more detail on federation settings, and specifically how domain allows and domain blocks work in combination, please see [the federation modes section](./federation_modes.md), and [the domain blocks section](./domain_blocks.md). + +#### Domain Blocks + +You can enter a domain to suspend in the search field, which will filter the list to show you if you already have a block for it. + +Clicking 'suspend' gives you a form to add a public and/or private comment, and submit to add the block. Adding a suspension will suspend all the currently known accounts on the instance, and prevent any new interactions with any user on the blocked instance. -### Bulk import/export -Through the link at the bottom of the Federation section (or going to `/settings/admin/federation/import-export`) you can do bulk import/export of your domain blocklist. +#### Domain Allows + +The domain allows section works much like the domain blocks section, described above, only for explicit domain allows rather than domain blocks. + +#### Bulk import/export + +Through the link at the bottom of the Federation section (or going to `/settings/admin/federation/import-export`) you can do bulk import/export of blocklists and allowlists.  Upon importing a list, either through the input field or from a file, you can review the entries in the list before importing a subset. You'll also be warned for entries that use subdomains, providing an easy way to change them to the main domain. -## Reports - +## Administration -The reports section shows a list of reports, originating from your local users, or remote instances (shown anonymously as just the name of the instance, without specific username). +Instance administration settings. + +### Actions + +Run one-off administrative actions. + +#### Media -Clicking a report shows if it was resolved (with the reasoning if available), more information, and a list of reported toots if selected by the reporting user. +You can use this section run a media action to clean up the remote media cache using the specified number of days. Media older than the given number of days will be removed from storage (s3 or local). Media removed in this way will be refetched again later if the media is required again. This action is functionally identical to the media cleanup that runs every night, automatically. + +#### Keys + +You can use this section to expire/invalidate public keys from the selected remote instance. The next time your instance receives a signed request using an expired key, it will attempt to fetch and store the public key again. + +### Custom Emoji -## Custom Emoji Custom Emoji will be automatically fetched when included in remote toots, but to use them in your own posts they have to be enabled on your instance. -### Local +#### Local +  This section shows an overview of all the custom emoji enabled on your instance, sorted by their category. Clicking an emoji shows it's details, and provides options to change the category or image, or delete it completely. The shortcode cannot be updated here, you would have to upload it with the new shortcode yourself (and optionally delete the old one). Below the overview you can upload your own custom emoji, after previewing how they look in a toot. PNG and (animated) GIF's are supported. -### Remote +#### Remote +  Through the 'remote' section, you can look up a link to any remote toots (provided the instance isn't suspended). If they use any custom emoji they will be listed, providing an easy way to copy them to the local emoji (for use in your own toots), or disable them ( hiding them from toots). **Note:** as the testrig server does not federate, this feature can't be used in development (500: Internal Server Error). +### Instance Settings + + + +Here you can set various metadata for your instance, like the displayed name/title, thumbnail image, description (HTML accepted), and contact username and email. |