docs(15.10): add user-visible changes missing from the 15.9 to 15.10 upgrade section

de/15.10/install/upgrade.rst

@@ -586,6 +586,8 @@ Bis 15.9 enthielten das Feld ``ip`` des Audit-Protokolls und das Feld ``clientIp
 
 Hinter einem Reverse-Proxy, der nicht in ``rate.limit.trusted.proxies`` steht, werden alle Anfragen mit der Adresse des Proxys erfasst. Um die Adresse des ursprünglichen Clients zu erfassen, fügen Sie die Adresse des Proxys zu ``rate.limit.trusted.proxies`` hinzu.
 
+Trägt eine Anfrage von einer Adresse, die nicht in ``rate.limit.trusted.proxies`` steht, ``X-Forwarded-For`` oder ``X-Real-IP``, schreibt 15.10 eine Warnung in ``fess.log``, die die Adresse der Quelle und ``rate.limit.trusted.proxies`` nennt. Die Warnung wird nach dem Start nur einmal geschrieben, nicht für jede Anfrage; sie nennt daher nur die erste solche Adresse und enthält nicht den Wert des Headers. Der Header wird weiterhin ignoriert, sodass sich außer dem Log nichts ändert. Da das Anmeldeformular dieselben Limits verwendet (siehe „Ratenbegrenzung des Anmeldeformulars“ weiter unten), wird jeder Client hinter einem solchen Proxy als eine Adresse gezählt, und sobald die fehlgeschlagenen Anmeldungen das Limit erreichen, werden Anmeldungen von allen abgelehnt. Sehen Sie die Warnung, fügen Sie die Adresse des Proxys zu ``rate.limit.trusted.proxies`` hinzu.
+
 .. _upgrade-1510-cipher-key:
 
 Warnung zu ``app.cipher.key``
@@ -600,6 +602,9 @@ Weitere Verhaltensänderungen
 - „Alle löschen“ in den Bildschirmen „Suche“ und „Crawling-Informationen“ der Administrationsoberfläche erfordert die Bearbeitungsrolle (``admin-searchlist``, ``admin-crawlinginfo``). Bis 15.9 war nur die Schaltfläche ausgeblendet: Anfragen von Benutzern, die nur eine Leserolle (eine Rolle mit der Endung ``-view``) hatten, wurden dennoch angenommen.
 - Der Zieltext (``output``) eines Eintrags im Zuordnungswörterbuch ist erforderlich. Bis 15.9 nahmen die Administrationsoberfläche und die Administrations-API einen Eintrag ohne ihn an und speicherten nichts.
 - Bei der Suche trifft ein einzelnes Wort in doppelten Anführungszeichen (etwa ``"less"``) nur auf dieses Wort zu. Bis 15.9 erhielt ein Wort mit mindestens ``query.boost.fuzzy.min.length`` (Standardwert ``4``) Zeichen zusätzlich Bedingungen für unscharfe Treffer, sodass Dokumente mit ``fess`` auch auf ``"less"`` passten. Wörter ohne Anführungszeichen und Wörter mit angegebenem Feld (etwa ``content:"less"``) sind unverändert.
+- ``suggest.popular.word.cache.expire`` wird in Sekunden gelesen, wie es ``fess_config.properties`` und :doc:`../config/properties` beschreiben. Bis 15.9 wurde der Wert als Minuten verwendet, sodass der Standardwert ``60`` beliebte Wörter 60 Minuten lang zwischenspeicherte; in 15.10 sind es 60 Sekunden. Um den längeren Cache beizubehalten, setzen Sie einen größeren Wert in Sekunden (``3600`` für 60 Minuten). Der Cache wird außerdem nach jedem Lauf des Suggest-Jobs geleert.
+- Der Abruf eines Dokuments über seine Dokument-ID wendet jetzt wie eine Suche den Filter des virtuellen Hosts an. Bis 15.9 wendeten ``/api/v2/cache/{docId}``, die Weiterleitung ``/go/``, Vorschaubilder, die Favoriten-Endpunkte und die übrigen Abrufe über die Dokument-ID nur den Rollenfilter an und antworteten daher bei passenden Rollen auch für ein Dokument eines anderen virtuellen Hosts. In 15.10 gilt ein solches Dokument als nicht gefunden. Wie bei einer Suche wird ein Dokument ohne Wert für den virtuellen Host nicht zurückgegeben, wenn für die Anfrage ein virtueller Host bestimmt wird. Bei einer Anfrage ohne bestimmten virtuellen Host (Standard-Host) ändert sich nichts.
+- Der Suggest-Job übernimmt keine Wörter mehr aus Dokumenten, die die Suche ausblendet. Ein Dokument ohne ``role``-Wert und ein Dokument mit einem Verweigerungseintrag (ein Wert, der mit ``role.search.denied.prefix`` (Standardwert ``D``) beginnt und auf den das Präfix eines Benutzers, einer Gruppe oder einer Rolle folgt, standardmäßig also ``D1``, ``D2`` oder ``DR``) werden übersprungen. Bis 15.9 wurden die Wörter solcher Dokumente allen Benutzern vorgeschlagen. Ein Dokument mit Erlaubnis- und Verweigerungseinträgen wird als Ganzes übersprungen, weil eine Suggest-Anfrage keine Verweigerung für einen einzelnen Benutzer ausdrücken kann. Suggest-Einträge, die bereits aus solchen Dokumenten entstanden sind, laufen über die übliche Bereinigung alter Suggest-Daten ab.
 
 .. _upgrade-1510-tika:
 
@@ -683,6 +688,41 @@ Steuerzeichen in audit.log
 
 Im LTSV-Format wird jedes Steuerzeichen sowie die Unicode-Zeilentrenner NEL, LS und PS in einem Feld durch ein Leerzeichen ersetzt (ein Tabulator durch einen Unterstrich), sodass ein eingegebener Benutzername keinen zweiten Datensatz beginnen kann. 15.9 ersetzte nur CR und LF.
 
+Rollen von Dateien aus ACLs
+---------------------------
+
+Beim Crawlen eines lokalen Dateisystems (``file:``-URLs), dessen Dateien ACLs haben (etwa NTFS), und mit ``file.role.from.file`` auf dem Standardwert ``true`` machte 15.9 jeden ACL-Eintrag einer Datei zu einer Rolle, die das Dokument lesen darf, unabhängig von Typ und Berechtigungen des Eintrags. Ein Benutzer, dem das Lesen verweigert wurde oder der nur Schreibzugriff erhielt, wurde dadurch zum Leser des indexierten Dokuments.
+
+15.10 prüft Typ und Berechtigungen jedes Eintrags:
+
+- Ein ALLOW-Eintrag, der das Lesen von Daten (``READ_DATA``) einschließt, gibt dem Benutzer oder der Gruppe wie bisher die Rolle.
+- Ein DENY-Eintrag, der ``READ_DATA`` einschließt, ergibt eine verweigerte Rolle: die Rolle mit vorangestelltem ``role.search.denied.prefix`` (Standardwert ``D``), demselben Präfix, das SMB-Crawls verwenden. Die Suche blendet das Dokument für diesen Benutzer oder diese Gruppe aus.
+- AUDIT- und ALARM-Einträge sowie Einträge ohne ``READ_DATA`` werden ignoriert.
+
+Die aus POSIX-Berechtigungen (Eigentümer und Gruppe) gelesenen Rollen bleiben unverändert.
+
+Ein Dokument behält die Rollen, mit denen es indexiert wurde, bis es erneut gecrawlt wird. Um die neuen Regeln auf vorhandene Dokumente anzuwenden, führen Sie den Dateicrawl erneut aus.
+
+LDAP: Organisationseinheiten für Rollen und verschachtelte Gruppen
+------------------------------------------------------------------
+
+Wenn |Fess| die Berechtigungen eines LDAP-/Active-Directory-Benutzers auflöst (siehe :doc:`../config/ldap-integration`), entscheidet der DN eines Gruppeneintrags, ob er eine Rolle (Berechtigungspräfix ``role.search.role.prefix``, Standardwert ``R``) oder eine Gruppe (``role.search.group.prefix``, Standardwert ``2``) ist. Bis 15.9 war ein Eintrag eine Rolle, wenn sein DN irgendwo den Text ``ou=role`` enthielt; auch ein Eintrag unter ``OU=Roles-Requests`` oder ``OU=RoleOwners`` war daher eine Rolle.
+
+15.10 zerlegt den DN und behandelt einen Eintrag nur dann als Rolle, wenn eine seiner ``ou``-Komponenten genau ``Role`` oder ``Roles`` lautet (ohne Beachtung der Groß- und Kleinschreibung). Jeder andere Eintrag ist eine Gruppe, ebenso ein Eintrag, dessen DN sich nicht zerlegen lässt.
+
+Die Einträge unter einer OU wie ``OU=Roles-Requests`` erhalten daher den Berechtigungsnamen einer Gruppe statt den einer Rolle (``2name`` statt ``Rname``), und Dokumente, deren Berechtigungen den alten Namen enthalten, treffen für die Benutzer dieser Gruppen nicht mehr zu. Haben Sie sich auf eine solche OU verlassen, verschieben Sie die Einträge nach ``OU=Role`` oder ``OU=Roles`` oder aktualisieren Sie die Berechtigungseinstellungen, die die alten Namen verwenden, und crawlen (oder indexieren) Sie erneut.
+
+Ist ``ldap.group.filter`` gesetzt (standardmäßig ist er leer), sucht |Fess| mit diesem Filter die Gruppen, die die Gruppen des Benutzers enthalten (verschachtelte Gruppen). Bis 15.9 wurden die DNs der Gruppen des Benutzers ohne Maskierung in diesen Filter eingesetzt. Ein DN mit einem maskierten Zeichen, etwa dem Komma in ``CN=Sales\, EMEA,...``, passte nicht, sodass die verschachtelten Gruppen einer solchen Gruppe ohne Fehlermeldung fehlten, und ein DN mit für LDAP-Filter besonderen Zeichen veränderte den Filter. 15.10 maskiert die DNs (RFC 4515). Die verschachtelten Gruppen solcher Gruppen werden nun gefunden, sodass die betroffenen Benutzer auch die Berechtigungen dieser Gruppen erhalten.
+
+Rollen in Anfragen ohne Cipher
+------------------------------
+
+|Fess| kann die Rollen eines Benutzers aus einem Anfrageparameter, einem Header oder einem Cookie lesen, wenn die Komponente ``roleQueryHelper`` in ``fess.xml`` ``parameterKey``, ``headerKey`` oder ``cookieKey`` setzt. Jeder Wert gilt als verschlüsselt, solange ``encryptedParameterValue``, ``encryptedHeaderValue`` oder ``encryptedCookieValue`` nicht auf ``false`` steht (alle drei haben den Standardwert ``true``).
+
+Bis 15.9 wurde ein Wert, der verschlüsselt sein sollte, als Klartext gelesen, wenn kein ``cipher`` gesetzt war; jeder Client konnte daher eine Rollenliste senden. 15.10 ignoriert einen solchen Wert und schreibt nach dem Start einmalig eine Warnung in ``fess.log``. Ein Wert, dessen Flag ``false`` ist, wird weiterhin unverändert gelesen, und mit gesetztem ``cipher`` wird ein Wert weiterhin entschlüsselt.
+
+Setzt Ihr ``roleQueryHelper`` einen der Schlüssel ohne ``cipher``, setzen Sie einen ``cipher`` und senden Sie verschlüsselte Werte, oder setzen Sie das Flag für unverschlüsselt gesendete Werte auf ``false``. In der mitgelieferten ``fess.xml`` sind diese Einstellungen auskommentiert, sodass eine Standardinstallation nicht betroffen ist.
+
 Änderungen für Plugin-Entwickler
 --------------------------------
 

en/15.10/install/upgrade.rst

@@ -572,6 +572,8 @@ Up to 15.9, the ``ip`` field of the audit log and the ``clientIp`` field of the
 
 Behind a reverse proxy that is not in ``rate.limit.trusted.proxies``, every request is recorded with the address of the proxy. To record the address of the original client, add the address of the proxy to ``rate.limit.trusted.proxies``.
 
+If a request from an address that is not in ``rate.limit.trusted.proxies`` carries ``X-Forwarded-For`` or ``X-Real-IP``, 15.10 writes a warning to ``fess.log`` that names the address of the source and ``rate.limit.trusted.proxies``. The warning is written once after startup, not for every request, so it names only the first such address, and it does not contain the value of the header. The header is still ignored, so nothing changes except the log. Because the login form uses the same limits (see "Login Form Rate Limit" below), every client behind such a proxy is counted as one address, and once the failed logins reach the limit, logins from all of them are refused. If you see the warning, add the address of the proxy to ``rate.limit.trusted.proxies``.
+
 .. _upgrade-1510-cipher-key:
 
 Warning for ``app.cipher.key``
@@ -586,6 +588,9 @@ Other Behavior Changes
 - "Delete all" in the "Search" and "Crawling Info" screens of the admin UI requires the edit role (``admin-searchlist``, ``admin-crawlinginfo``). Up to 15.9, only the button was hidden: requests from a user who had only a view role (a role with the ``-view`` suffix) were still accepted.
 - The converted text (``output``) of a mapping dictionary item is required. Up to 15.9, the admin UI and the admin API accepted an item without it and stored nothing.
 - In a search, a single word in double quotes (such as ``"less"``) matches only that word. Up to 15.9, a word at least ``query.boost.fuzzy.min.length`` (default ``4``) long also got fuzzy match conditions, so documents containing ``fess`` also matched ``"less"``. Unquoted words and words with a field specified (such as ``content:"less"``) are unchanged.
+- ``suggest.popular.word.cache.expire`` is read as seconds, as ``fess_config.properties`` and :doc:`../config/properties` describe. Up to 15.9 the value was used as minutes, so the default ``60`` kept popular words cached for 60 minutes; in 15.10 it is 60 seconds. To keep the longer cache, set a larger value in seconds (``3600`` for 60 minutes). The cache is also cleared after every run of the suggest job.
+- Looking up a document by its document ID now applies the virtual host filter, as a search does. Up to 15.9, ``/api/v2/cache/{docId}``, the ``/go/`` redirect, thumbnails, the favorite endpoints and the other lookups by document ID applied only the role filter, so when the roles matched they also answered for a document of another virtual host. In 15.10 such a document is treated as not found. As in a search, a document that has no virtual host value is not returned when a virtual host is resolved for the request. Nothing changes for a request with no virtual host resolved (the default host).
+- The suggest job no longer takes words from a document that search hides. It skips a document that has no ``role`` value and a document that has a denied entry (a value that starts with ``role.search.denied.prefix`` (default ``D``) followed by the prefix of a user, group or role, that is ``D1``, ``D2`` or ``DR`` by default). Up to 15.9, the words of such documents were suggested to everyone. A document that has both allowed and denied entries is skipped as a whole, because a suggest request cannot express a denial for one user. Suggest entries already created from such documents expire through the usual purge of old suggest data.
 
 .. _upgrade-1510-tika:
 
@@ -669,6 +674,41 @@ Control Characters in audit.log
 
 In the LTSV format, every control character, and the Unicode line separators NEL, LS and PS, in a field is replaced by a space (a tab by an underscore), so a typed user name cannot start a second record. 15.9 replaced only CR and LF.
 
+Roles of Files Read from ACLs
+-----------------------------
+
+For a crawl of a local file system (``file:`` URLs) whose files have ACLs, such as NTFS, with ``file.role.from.file`` left at the default ``true``, 15.9 turned every ACL entry of a file into a role that may read the document, whatever the type or the permissions of the entry. A user who was denied reading, or who was granted only write access, therefore became a reader of the indexed document.
+
+15.10 looks at the type and the permissions of each entry:
+
+- An ALLOW entry that includes read data (``READ_DATA``) gives the user or group the role, as before.
+- A DENY entry that includes ``READ_DATA`` gives a denied role: the role with ``role.search.denied.prefix`` (default ``D``) in front of it, the same prefix that SMB crawls use. Search hides the document from that user or group.
+- AUDIT and ALARM entries, and entries that do not include ``READ_DATA``, are ignored.
+
+The roles read from POSIX permissions (owner and group) are unchanged.
+
+A document keeps the roles it was indexed with until it is crawled again. To apply the new rules to the documents you already have, run the file crawl again.
+
+LDAP Role Organizational Units and Nested Groups
+------------------------------------------------
+
+When |Fess| resolves the permissions of an LDAP / Active Directory user (see :doc:`../config/ldap-integration`), the DN of a group entry decides whether it is a role (permission prefix ``role.search.role.prefix``, default ``R``) or a group (``role.search.group.prefix``, default ``2``). Up to 15.9, an entry was a role when its DN contained the text ``ou=role`` anywhere, so an entry under ``OU=Roles-Requests`` or ``OU=RoleOwners`` was a role, too.
+
+15.10 parses the DN and treats an entry as a role only when one of its ``ou`` components is exactly ``Role`` or ``Roles`` (case-insensitive). Every other entry is a group, and so is an entry whose DN cannot be parsed.
+
+The entries under an OU such as ``OU=Roles-Requests`` therefore get the permission name of a group instead of that of a role (``2name`` instead of ``Rname``), and documents whose permissions hold the old name no longer match the users of those groups. If you relied on such an OU, move the entries into ``OU=Role`` or ``OU=Roles``, or update the permission settings that use the old names, and crawl (or reindex) again.
+
+When ``ldap.group.filter`` is set (it is blank by default), |Fess| uses it to look up the groups that contain the groups of the user (nested groups). Up to 15.9, the DNs of the user's groups were put into that filter without escaping. A DN with an escaped character, such as the comma of ``CN=Sales\, EMEA,...``, did not match, so the nested groups of such a group were silently missing, and a DN that contained characters special to LDAP filters changed the filter. 15.10 escapes the DNs (RFC 4515). The nested groups of such groups are now found, so the users concerned get the permissions of those groups, too.
+
+Roles Sent in a Request Without a Cipher
+----------------------------------------
+
+|Fess| can read the roles of a user from a request parameter, header or cookie when the ``roleQueryHelper`` component in ``fess.xml`` sets ``parameterKey``, ``headerKey`` or ``cookieKey``. Each value is expected to be encrypted unless ``encryptedParameterValue``, ``encryptedHeaderValue`` or ``encryptedCookieValue`` is set to ``false`` (all three default to ``true``).
+
+Up to 15.9, a value that was expected to be encrypted was read as plain text when no ``cipher`` was set, so any client could send a role list. 15.10 ignores such a value and writes a warning to ``fess.log`` once after startup. A value whose flag is ``false`` is still read as it is, and a value is still decrypted when a ``cipher`` is set.
+
+If your ``roleQueryHelper`` sets one of the keys without a ``cipher``, set a ``cipher`` and send encrypted values, or set the flag to ``false`` for the values you send unencrypted. The shipped ``fess.xml`` has these settings commented out, so a default installation is not affected.
+
 Changes for Plugin Developers
 -----------------------------