diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/general.md | 4 | ||||
| -rw-r--r-- | docs/configuration/trusted_proxies.md | 71 |
2 files changed, 72 insertions, 3 deletions
diff --git a/docs/configuration/general.md b/docs/configuration/general.md index 50b04bbe1..16589c842 100644 --- a/docs/configuration/general.md +++ b/docs/configuration/general.md @@ -1,8 +1,6 @@ # General -The top-level configuration for GoToSocial, including basic things like host, port, bind address and transport protocol. - -The only things you *really* need to set here are `host`, which should be the hostname where your instance is reachable, and probably `port`. +The top-level configuration for GoToSocial, including basic things like host, port, bind address, and trusted-proxies. ## Settings diff --git a/docs/configuration/trusted_proxies.md b/docs/configuration/trusted_proxies.md new file mode 100644 index 000000000..6852e22e1 --- /dev/null +++ b/docs/configuration/trusted_proxies.md @@ -0,0 +1,71 @@ +# Trusted Proxies + +To correctly enforce [rate limiting](../api/ratelimiting.md), GoToSocial relies on the concept of "trusted proxies" in order to accurately determine the IP address of clients accessing your server. + +A "trusted proxy" is an intermediate network hop that GoToSocial can be instructed to trust to provide a correct client IP address. + +For example, if you are running in a reverse proxy configuration with Docker + Nginx, then the Docker network address of Nginx should be configured as a trusted proxy, since all traffic from the wider internet will come into GoToSocial via Nginx. + +Without setting `trusted-proxies` correctly, GoToSocial will see all incoming client IP addresses as the same address, which leads to rate limiting issues, since GoToSocial uses client IP addresses to bucket rate limits. + +## tl;dr: How to set `trusted-proxies` correctly + +If your `trusted-proxies` setting is not correctly configured, you may see the following warning on the web view of your instance (v0.18.0 and above): + +> Warning! It looks like trusted-proxies is not set correctly in this instance's configuration. This may cause rate-limiting issues and, by extension, federation issues. +> +> If you are the instance admin, you should fix this by adding `SUGGESTED_IP_RANGE` to your trusted-proxies. + +To resolve this, copy the IP range in the message, and edit your `config.yaml` file to add the IP range to your `trusted-proxies`. + +!!! tip "You may be getting rate limited even if you don't see the above warning!" + If you're on a version of GoToSocial below v0.18.0, or you're running behind a CDN such as Cloudflare (not recommended), you won't see a warning message. Instead, you'll see in your GoToSocial logs that all client IPs are the same address. In this case, take the recurring client IP value as `SUGGESTED_IP_RANGE`. + +In this example, we assume `SUGGESTED_IP_RANGE` to be `172.17.0.1/16` (the default Docker bridge network subnet). + +Before (default config): + +```yaml +trusted-proxies: + - "127.0.0.1/32" + - "::1" +``` + +After (new config): + +```yaml +trusted-proxies: + - "172.17.0.1/16" + - "127.0.0.1/32" + - "::1" +``` + +If you are using [environment variables](../configuration/index.md#environment-variables) to configure your instance, you can configure `trusted-proxies` by setting the environment variable `GTS_TRUSTED_PROXIES` to a comma-separated list of IP ranges, like so: + +```env +GTS_TRUSTED_PROXIES="172.17.0.1/16,127.0.0.1/32,::1" +``` + +If you are using docker compose, your docker-compose.yaml file should look something like this after the change (note that yaml uses `: ` and not `=`): + +```yaml +################################ +# BLAH BLAH OTHER CONFIG STUFF # +################################ + environment: + ############################ + # BLAH BLAH OTHER ENV VARS # + ############################ + ## For reverse proxy setups: + GTS_TRUSTED_PROXIES: "172.17.0.1/16,127.0.0.1/32,::1" +################################ +# BLAH BLAH OTHER CONFIG STUFF # +################################ +``` + +Once you have made the necessary configuration changes, restart your instance and refresh the home page. If the message is gone, then the problem is resolved! + +If you still see the warning message but with a different suggested IP range to add to `trusted-proxies`, then follow the same steps as above again, including the new suggested IP range in your config in addition to the one you just added. + +!!! tip "Cloudflare IP Addresses" + If you are running with a CDN/proxy such as Cloudflare in front of your GoToSocial instance (not recommended), then you may need to add one or more of the Cloudflare IP addresses to your `trusted-proxies` in order to have rate limiting work properly. You can find a list of Cloudflare IP addresses here: https://www.cloudflare.com/ips/ |