diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index c5d504d2..f6fc0f3d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,6 +3,7 @@ - [Introduction](introduction.md) - [Configuration](configuration.md) + - [Rate Limiting](configuration/rate-limiting.md) - [Delegation](delegation.md) - [Deploying](deploying.md) - [Generic](deploying/generic.md) diff --git a/docs/configuration.md b/docs/configuration.md index 61becfc3..5ba282a1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,6 +11,8 @@ Conduit's configuration file is divided into the following sections: - [Global](#global) + - [Media](#media) + - [Rate Limiting](configuration/rate-limiting.md) - [TLS](#tls) - [Proxy](#proxy) diff --git a/docs/configuration/rate-limiting.md b/docs/configuration/rate-limiting.md new file mode 100644 index 00000000..ce3688a7 --- /dev/null +++ b/docs/configuration/rate-limiting.md @@ -0,0 +1,55 @@ +# Rate Limiting +Conduit [rate-limits](https://en.wikipedia.org/wiki/Rate_limiting) security/privacy sensitive and +resource intensive endpoints, to protect against things like: +- Denial of service attacks, caused by things like overloading the media store +- Abuse by spammers, attempting to make use of your server to send spam in mass, which usually + leads to your server being put in policy lists, making it unable to participate in many rooms. +> **Note**: The easiest way to prevent this is to disable public registration, and use a strong + registration token to allow selective registration. +- Brute-force attacks to guess user's password or the servers registration token, the former leading + to potential impersination, as well as denial of service if an admin account is accessed. + +## Presets + +By default, Conduit uses the rate-limiting preset `private_small`, but there are more available if +this isn't the type of server you're planning on running: +- `private_small`: The default preset, designed for small private servers (i.e. single-user or for + family and friends). +- `private_medium`: Designed for medium-sized private servers (e.g. for an entire school class or year-group) +- `public_medium`: For medium-sized public servers (i.e. you intend 20-100 users to actively use it). +- `public_large`: For larger public server (i.e. you intend 200-1000 users to actively use it). + +Here is an example configuration using the `private_medium` preset: +```toml +[global.rate_limiting] +preset = "private_medium" +``` + +## Overrides + +Despite the variety of presets available, you may find the presets to be too restrictive and/or liberal. +You can override all the preset configurations directly in the configuration, and if you think your overrides +should be part of the preset, you can contribute and change them! + +The overrides are split into `client` and `federation` sections, for limits that apply to the +[client](https://spec.matrix.org/v1.17/client-server-api/) and +[federation](https://spec.matrix.org/v1.17/server-server-api/) APIs respectively, which are both +then split into `target` and `global` sections, which apply to specific [targets](#targets) and globally respectively. + +### Restrictions + +{{#include ../../target/docs/rate-limiting.md:restrictions}} + +### Targets + +A target is any client that call's Conduit's API endpoints, and are identified by one of the following: +- A user ID +- A Server Name (domain) +- An appservice ID +- An IP address, if it cannot be addressed by any of the above (i.e. the client is not authenticated) + +The rate limiting configurations under both `target` parts allow you to configure how many +resources/requests each unique client can access within the configured timeframe. +For example, while on a small server you might allow for all logged-in users to send out 100 invites +per day between them, you can set a cap of 5 for each individual user, not only so that they can't +use up the entire global cap, but also prevent potential spam from being spread by that user alone.