From c729aef849f06c7dce64f1ee243f018347dbc144 Mon Sep 17 00:00:00 2001 From: Michael Peter Christen Date: Tue, 14 Jul 2026 22:18:11 +0200 Subject: Server-validated X-Real-IP proxy handling, publicPort lifecycle fix, peer-statistic iam parameter, transfer-IP fallback, and matching tests/docs --- help/AccessTracker_p.md | 12 ++++++------ help/SettingsAck_p.md | 9 ++++++++- help/yacy/hello.md | 7 +++++++ help/yacy/list.md | 7 +++++++ help/yacy/message.md | 7 +++++++ help/yacy/profile.md | 7 +++++++ help/yacy/query.md | 7 +++++++ help/yacy/search.md | 10 +++++++++- help/yacy/transferRWI.md | 7 +++++++ 9 files changed, 65 insertions(+), 8 deletions(-) (limited to 'help') diff --git a/help/AccessTracker_p.md b/help/AccessTracker_p.md index 09684e4bc..63a56634b 100644 --- a/help/AccessTracker_p.md +++ b/help/AccessTracker_p.md @@ -63,12 +63,12 @@ GET or POST /AccessTracker_p.html?host=...&page=... Expect observations: counts, logs, queues, timing, network rows, thread states, or resource values. Monitoring does not fix the issue by itself; it points to the next page or setting to change. When YaCy is reached through a reverse proxy, Access Tracker uses `X-Real-IP` -only when the proxy's direct socket IP matches one of the comma-separated regular -expressions in `server.reverseProxy.trusted`. Loopback proxies are trusted by -default. Authentication and access-control decisions continue to use the direct -socket IP, not the forwarded address. The reverse proxy must overwrite -`X-Real-IP` with the client address; it must not pass a client-supplied value -unchanged. +only when the proxy's direct socket IP matches one of the comma-separated +regular expressions in `server.reverseProxy.trusted` and the header contains +one valid IPv4 or IPv6 address. Loopback proxies are trusted by default. +Authentication and access-control decisions continue to use the direct socket +IP, not the forwarded address. The reverse proxy must overwrite `X-Real-IP` +with the client address; it must not pass a client-supplied value unchanged. ## Related Pages diff --git a/help/SettingsAck_p.md b/help/SettingsAck_p.md index 20d9224fa..96844bfa9 100644 --- a/help/SettingsAck_p.md +++ b/help/SettingsAck_p.md @@ -58,11 +58,12 @@ The table explains values that an agent or script must set deliberately. Paramet | `fileHost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | | `msgForwardingEnabled` | Enables the named feature. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. | | `port` | HTTP port where YaCy listens. Values below 1024 are ignored by this form; changing the port triggers reconnect/redirect behavior. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. | +| `publicPort` | Optional public non-TLS HTTP port, from 1 through 65535, advertised in YaCy's seed/P2P metadata. It takes precedence over UPnP and the local listening port. An empty value disables the manual override. | Processed with the `serveraccount` settings action. Invalid, non-numeric, zero, or out-of-range values leave the previous setting unchanged. Set it when NAT or a reverse proxy exposes YaCy on a different external port. | | `proxyaccess` | Saves the proxy client IP-number filter. | Changes proxy access scope; verify the filter before submitting. | | `proxyfilter` | Filter expression. It decides which records are included, excluded, displayed, exported, or processed on this page. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | | `remoteProxyHost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | | `remoteProxyUser` | User or account value. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | -| `serveraccount` | User or account value. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `serveraccount` | Action marker whose presence applies the Server Access form, including `fileHost`, `staticIP`, `publicPort`, and `serverfilter`. Its submitted value is not interpreted. | Requires administrator access and a valid transaction token. Include the complete Server Access form state because the action processes its related fields together. | | `serverfilter` | Filter expression. It decides which records are included, excluded, displayed, exported, or processed on this page. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | | `serveruser` | User or account value. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | | `urlproxydomains` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | @@ -75,6 +76,12 @@ Example request shape: GET or POST /SettingsAck_p.html?port=...&adminaccount=...&adminpw1=...&adminpw2=...&adminuser=... ``` +For a server-access form submission, `serveraccount` selects the action and +`publicPort` carries the optional override. A valid value is stored and applied +to the current peer seed. Clearing the value removes the override; subsequent +seed refreshes then use the UPnP mapping when available, otherwise the local +HTTP listening port. The setting does not override the public TLS port. + ## What To Expect A successful change is visible as a saved value, a confirmation, or changed behavior on a related page. Some settings take effect immediately; others require reconnecting, reloading translations, restarting services, or watching the status page. diff --git a/help/yacy/hello.md b/help/yacy/hello.md index f73593ce5..bda5bad2c 100644 --- a/help/yacy/hello.md +++ b/help/yacy/hello.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/hello.java`. diff --git a/help/yacy/list.md b/help/yacy/list.md index 546f4aa24..cc6f59848 100644 --- a/help/yacy/list.md +++ b/help/yacy/list.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/list.java`. diff --git a/help/yacy/message.md b/help/yacy/message.md index aeeab8bf7..d8a4fec12 100644 --- a/help/yacy/message.md +++ b/help/yacy/message.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/message.java`. diff --git a/help/yacy/profile.md b/help/yacy/profile.md index 53d642f76..303829a6f 100644 --- a/help/yacy/profile.md +++ b/help/yacy/profile.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/profile.java`. diff --git a/help/yacy/query.md b/help/yacy/query.md index aa785593b..c385ae264 100644 --- a/help/yacy/query.md +++ b/help/yacy/query.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/query.java`. diff --git a/help/yacy/search.md b/help/yacy/search.md index e8cba7e54..c7b3387e8 100644 --- a/help/yacy/search.md +++ b/help/yacy/search.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/search.java`. @@ -53,6 +60,7 @@ The table explains values that an agent or script must set deliberately. Paramet | `contentdom` | Content domain filter. Common values are `all`, `text`, `image`, `audio`, `video`, and `app`; use it to ask for web pages, media, or application documents deliberately. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | | `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | | `filter` | Filter text or expression used to narrow the displayed records. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `iam` | Twelve-character enhanced-Base64 seed hash of the requesting YaCy peer. When it identifies a known peer, YaCy uses it for search-statistics attribution so peers sharing an address behind NAT remain distinguishable. | This is attribution metadata, not an independent authentication credential. Missing, malformed, or unknown hashes fall back to the effective request client IP. | | `language` | Interface language. Values are `browser` for the browser-preferred language, `default` for English, or a language code such as `de`, `fr`, `es`, `zh`, `ja`, or `ko`. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. | | `query` | Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | | `sitehost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | @@ -63,7 +71,7 @@ The table explains values that an agent or script must set deliberately. Paramet Example request shape: ```http -GET or POST /yacy/search.html?language=...&query=...&contentdom=...&abstracts=...&author=... +GET or POST /yacy/search.html?iam=...&language=...&query=...&contentdom=...&abstracts=...&author=... ``` ## What To Expect diff --git a/help/yacy/transferRWI.md b/help/yacy/transferRWI.md index 3f7fe06cf..5cea79956 100644 --- a/help/yacy/transferRWI.md +++ b/help/yacy/transferRWI.md @@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v This is a peer-service endpoint for YaCy peer communication, not a normal editing page. +Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and +routing address only when the proxy socket IP matches +`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6 +address. Otherwise YaCy uses the socket IP. Authentication and access control +always use the socket IP. The proxy must overwrite, not pass through, any +client-supplied `X-Real-IP` value. + ## Automation And API Page backend: `source/net/yacy/htroot/yacy/transferRWI.java`. -- cgit v1.2.3