case 4732 - trusted reverse proxies setting

New config setting AYANOVA_TRUSTED_PROXIES (IP addresses or CIDR networks)
for reverse proxies on another computer: their X-Forwarded-For is used, a
chain of trusted proxies is followed, invalid entries are warned at boot.
X-Forwarded-For from a proxy that is not trusted logs one warning per server
start naming the proxy's address. Without the setting nothing changes (only
a loopback proxy is trusted). Shown in server info; manual page, Linux install
note, changelog. F6 follow-up recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/8.0/ayanova/docs/changelog.md

@@ -28,6 +28,7 @@ IN PROGRESS
 - Server: removed an unused internal performance profiling component.
 - Server: AyaNova now checks the email (SMTP) server's security certificate when sending email. If your mail server uses a self-signed or internal certificate and email notifications stop after upgrading, see [SMTP certificate check](ops-config-smtp-accept-any-certificate.md).
 - Server: after repeated failed login attempts, further attempts for that login, or from that address, are refused for a few minutes.
+- Server: new [trusted reverse proxies](ops-config-trusted-proxies.md) setting for a reverse proxy that runs on a different computer from the AyaNova server, so AyaNova sees each user's own address.
 - Server: the server information page at `/api/v8/` no longer shows license details.
 - Server: business logo uploads must be PNG, JPEG, GIF, WebP or SVG images, and need full rights to global settings. See [business logos](adm-global-logo.md).
 - Server: when a user's password is reset or set by an administrator, or their login is disabled, they are signed out and must sign in again.

docs/8.0/ayanova/docs/ops-config-environment-variables.md

@@ -102,3 +102,4 @@ Command line parameters are appended to the command to start the ayanova server,
 ### SECURITY
 
 - [AYANOVA_SET_SUPERUSER_PW](ops-config-set-superuser-pw.md)
+- [AYANOVA_TRUSTED_PROXIES](ops-config-trusted-proxies.md)

docs/8.0/ayanova/docs/ops-config-trusted-proxies.md

@@ -0,0 +1,56 @@
+# Trusted reverse proxies setting
+
+When AyaNova is reached through a reverse proxy server (for example NGINX, Apache, IIS, a load balancer or a cloud service in front of AyaNova), every connection AyaNova receives comes from the proxy, not from the user's computer. The proxy passes along the user's real address in an `X-Forwarded-For` header.
+
+AyaNova uses the user's address to limit repeated failed login attempts and to record where logins come from in the [server log](ops-log.md). Because anyone can add an `X-Forwarded-For` header to a request, AyaNova only accepts it from a proxy it trusts.
+
+A reverse proxy running on the **same computer** as the AyaNova server and connecting to it through `localhost` or `127.0.0.1` is always trusted. This is how our [Linux server](ops-install-linux-server.md) and [Windows IIS](ops-install-windows-iis.md) installation instructions set it up, and nothing needs to be done.
+
+## When this setting is needed
+
+If the reverse proxy runs on a **different computer** from the AyaNova server, AyaNova does not trust it by default. All users then appear to come from the proxy's address, and they share a single limit on failed login attempts: repeated failed logins by one person can then refuse logins for everyone connecting through the proxy for a few minutes.
+
+When this happens, the AyaNova server log records a warning once after each server start, naming the address of the proxy:
+
+`A request came through a reverse proxy at 10.0.0.5 that is not trusted...`
+
+If that address is your reverse proxy, add it to this setting.
+
+## Default
+
+If this setting is not specified only a reverse proxy on the same computer is trusted.
+
+## Overriding
+
+AyaNova expects this value to be provided by a config.json property, environment variable or command line parameter named
+
+`AYANOVA_TRUSTED_PROXIES`
+
+The value is a list of the IP addresses of your reverse proxies, separated by commas. A whole network can be given in CIDR notation, for example `10.0.0.0/24` for the addresses `10.0.0.0` to `10.0.0.255`. If there is more than one proxy in a chain (for example a load balancer in front of a reverse proxy), list each of them.
+
+Only list addresses of your own proxy servers. Any computer listed here can tell AyaNova a user's address, so never list an address range that ordinary users connect from.
+
+An entry that is not a valid IP address or network is ignored and the AyaNova server log records a warning when the server starts.
+
+Example config.json entry
+
+```json
+{
+  ...other properties...
+  "AYANOVA_TRUSTED_PROXIES": "10.0.0.5, 10.0.1.0/24"
+}
+```
+
+Example command line parameter
+
+`ayanova.exe --AYANOVA_TRUSTED_PROXIES="10.0.0.5, 10.0.1.0/24"`
+
+Example environment variable
+
+Windows
+
+`set "AYANOVA_TRUSTED_PROXIES=10.0.0.5, 10.0.1.0/24"`
+
+Linux
+
+`export AYANOVA_TRUSTED_PROXIES="10.0.0.5, 10.0.1.0/24"`

docs/8.0/ayanova/docs/ops-install-linux-server.md

@@ -323,6 +323,8 @@ These instructions will assume use of a free SSL certificate from [LetsEncrypt](
 
 We will provide instructions for using the free and open source [NGINX](https://nginx.org/) as a reverse proxy server, if you already have another server capable of being a reverse proxy (such as Apache) you will need to adapt these instructions to match your situation.
 
+These instructions run the reverse proxy on the same server as AyaNova. If your reverse proxy runs on a different computer, see [trusted reverse proxies](ops-config-trusted-proxies.md).
+
 #### A\. Install NGINX
 
 Install NGINX to be the reverse proxy server:

docs/8.0/ayanova/mkdocs.yml

@@ -200,6 +200,7 @@ nav:
           - "SMTP certificate check": "ops-config-smtp-accept-any-certificate.md"
           - "Security and JWT web tokens": "ops-config-jwt-secret.md"
           - "SuperUser password reset": "ops-config-set-superuser-pw.md"
+          - "Trusted reverse proxies": "ops-config-trusted-proxies.md"
           - "Server error codes": "ops-error-codes.md"
           - "Migrating from AyaNova 7": "ops-import-v7.md"
           - "Metrics": "ops-metrics.md"