Improve documentation for TRUSTED_PROXY_IP (#1144)

* Improve documentation for TRUSTED_PROXY_IP

The documentation previously only indicated that `localhost` was trusted, but it appears that all private networks are trusted by default. I believe this because:

- I'm running my web and streaming processes within Docker containers and running Nginx on the Docker host. I believe they communicate over a 172.16.0.0/12 network that Docker creates. I tried looking at logs a bit and it _seems_ like things are working correctly. But if anyone has suggestions on how to verify that my Mastodon processes are recording the correct client IP, please let me know! We could include that advice in this documentation.
- I looked at the source code a bit and it appears that both the streaming and web processes use localhost and the private network ranges. But this is really my first time looking at the Mastodon code and I don't even know Ruby, so please double check me!
  - I believe the streaming processes uses Express JS. I believe it sets the trusted proxy IP [here](d11d15748c/streaming/index.js (L150)). Express documents the `loopback` and `uniquelocal` values [here](https://expressjs.com/en/guide/behind-proxies.html).
  - I'm less certain about web. It looks like the env var is parsed [here](d11d15748c/config/environments/production.rb (L44-L45)). It looks like `trusted_proxies` will be unset if the env var is unset. And maybe that results in [this check](https://github.com/mastodon/mastodon/blob/main/config/initializers/trusted_proxies.rb) getting bypassed? But it looks like Action Dispatch does it's own check [here](https://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html)?

* Try to improve the phrasing

Specifically I tried to make it less likely that people would do the wrong thing if they're using Cloudflare or a similar proxy service. It does seem pretty wordy now. I'm open to suggestions.
This commit is contained in:
Mark Doliner 2023-01-06 01:54:14 -05:00 committed by GitHub
parent 0b183dff3a
commit 17a5e151a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 2 deletions

View File

@ -202,7 +202,17 @@ Determines the amount of logs generated by Mastodon. Defaults to `info`, which g
#### `TRUSTED_PROXY_IP`
If your Mastodon web process is on the same machine as your reverse proxy (e.g. nginx), then you don't need this setting. Otherwise, you need to set it to the IP from which your reverse proxy sends requests to Mastodon's web process, otherwise Mastodon will record the reverse proxy's own IP as the IP of all requests, which would be bad because IP addresses are used for important rate limits and security functions.
Tells the Mastodon web and streaming processes which IPs act as your trusted reverse proxy (e.g. nginx, Cloudflare). It affects how Mastodon determines the source IP of each request, which is used for important rate limits and security functions. If the value is set incorrectly then Mastodon could use the IP of the reverse proxy instead of the actual source.
By default the loopback and private network address ranges are trusted. Specifically:
* `127.0.0.1/8`
* `::1/128`
* `10.0.0.0/8`
* `172.16.0.0/12`
* `192.168.0.0/16`
* `fc00::/7`
If you're using a single reverse proxy and it runs on the same machine or is in the same private network as your Mastodon web and streaming processes then you most likely don't need to modify this setting and can use the default. Or if you're using multiple reverse proxy servers and they're all in the same private network as your Mastodon web and streaming processes then, again, the default should be fine. However, if you're using a reverse proxy server that reaches your Mastodon web and streaming servers via a public IP address (for example if you're using Cloudflare or a similar proxy) then you'll need to set this variable. It should be the IPs of all reverse proxies in use, as a comma-separated list of IPs or IP ranges using [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). Note that when this variable is set the default ranges (mentioned above) will no longer be trusted, so if you have both an external reverse proxy _and_ a proxy on localhost then you must include the IPs (or IP ranges) of both.
#### `SOCKET`
@ -656,4 +666,4 @@ Defaults to `512`.
#### `GITHUB_API_TOKEN`
Used in a rake task for generating AUTHORS.md from Github commit history.
Used in a rake task for generating AUTHORS.md from Github commit history.