docs: Hostnames

docs/configuration/examples/config.yml

@@ -1,6 +1,8 @@
 # Example Config (all configurations shown)
 service:
   port: 8880
+  hostnames:
+    - mydomain.com
 
 api:
   url: http://signal-api:8080

docs/configuration/hostnames.md

@@ -0,0 +1,21 @@
+---
+title: Hostnames
+---
+
+# Hostnames
+
+Hostnames can be set to create isolated realms or to restrict access by limiting to a only a small subset of hostnames.
+
+Add hostnames, that are allowed to be used in `service.hostnames`. (default: all)
+
+```yaml
+service:
+  hostnames:
+    - mydomain.com
+```
+
+## Usage behind Proxy
+
+For clients behind proxies IPs cannot be reliably determined without using the `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-Port` HTTP headers.
+
+For **Secured Signal API** to trust a proxy it must be added to the trusted proxies, read more [here](./trusted-proxies).

docs/configuration/ip-filters.md

@@ -57,7 +57,7 @@ By default, adding an IP or range explicitly allows it, use `!` to block it inst
 
 ## Clients behind Proxies
 
-For clients behind proxies IPs cannot be reliably determined without trusting the `X-Forwarded-For` HTTP header.
+For clients behind proxies, IPs cannot be reliably determined without trusting the `X-Forwarded-For` HTTP header.
 In order for **Secured Signal API** to trust the _XFF_ header it has to trust the request's originating proxy.
 
 Read more about trusted proxies [here](./trusted-proxies).

docs/configuration/trusted-proxies.md

@@ -6,16 +6,21 @@ title: Trusted Proxies
 
 Proxies can be marked as trusted.
 
-When determining the IP of a client behind a proxy it is important to use the `X-Forwarded-For` header,
-but as you might know anyone can set headers (spoofing possible).
-
-To prevent IP spoofing you should only trust the HTTP headers of trusted proxies.
-Otherwise, malicious actors may change the `X-Forwarded-For` header to be able to bypass block list or rate limits.
-
 Add proxies to be trusted in `access.trustedProxies`.
 
 ```yaml
 access:
   trustedProxies:
     - 172.20.0.100
 ```
+
+## `X-Forwarded-*` Headers
+
+HTTP listeners only get the `proto://host:port/uri` from the incoming request, but proxies often redirect requests causing modified request URLs
+`http://sec-signal-api:8880`.
+
+To get the origin URL you have to use the `X-Forwarded-*` headers, but as you might know anyone can set headers (spoofing possible).
+This means you should only trust _XF_ headers from trusted sources,
+otherwise, malicious actors can change any `X-Forwarded-*` headers to be able to bypass block list, rate limits, hostname restrictions, … .
+
+This also applies to determining the IP of a client behind a proxy, so it is extremely important to allow for using the _XF_ headers when a proxy is trusted.