docs: answer the file server search question the site never answers

de/articles/file-server-search.rst

@@ -0,0 +1,156 @@
+=============================================
+Volltextsuche für Dateiserver mit Open Source
+=============================================
+
+Einführung
+==========
+
+Je mehr Dateiserver die einzelnen Abteilungen aufstellen, desto weniger weiß irgendjemand noch, wo ein bestimmtes Dokument liegt. Die Windows-Suche arbeitet immer nur in einem freigegebenen Ordner und reicht nicht über Servergrenzen hinweg, und die Volltextsuche eines NAS endet an dessen Gehäuse.
+
+Ein Ausweg ist ein eigener Volltextsuchserver vor den Dateiservern. Diese Seite sammelt, was vor dem Einsatz von Fess, einem quelloffenen Volltextsuchserver, an dieser Stelle zu prüfen ist.
+
+Für wen diese Seite gedacht ist
+===============================
+
+- Alle, die mit der Suche auf einem internen Dateiserver oder NAS zu kämpfen haben
+- Alle, die Volltextsuche prüfen und wissen möchten, ob Open Source dafür ausreicht
+- Alle, die Suche einführen wollen, ohne bestehende Zugriffsrechte anzutasten
+
+Fess steht unter der Apache License 2.0 und verursacht keine Lizenzkosten.
+
+Wo die Dateien liegen dürfen
+============================
+
+Der Datei-Crawler von Fess beherrscht die folgenden Protokolle. Eingerichtet werden sie in der Verwaltungsoberfläche unter [Crawler] > [Dateisystem] als Start-URL des Crawls.
+
+.. list-table:: Unterstützte Protokolle
+   :header-rows: 1
+   :widths: 12 33 55
+
+   * - Protokoll
+     - URL-Form
+     - Typischer Einsatz
+   * - ``file``
+     - ``file:///home/share/documents/``
+     - Ein Verzeichnis auf dem Rechner, der Fess ausführt, einschließlich eines bereits eingehängten NAS
+   * - ``smb``
+     - ``smb://fileserver.example.com/share/``
+     - Windows-Dateifreigaben, von SMB 2.0.2 bis SMB 3.1.1
+   * - ``smb1``
+     - ``smb1://fileserver.example.com/share/``
+     - Ältere Geräte, die nur SMB1/CIFS sprechen
+   * - ``ftp``
+     - ``ftp://fileserver.example.com/pub/``
+     - FTP-Server
+   * - ``s3``
+     - ``s3://bucket-name/prefix/``
+     - Amazon S3 und S3-kompatibler Objektspeicher
+   * - ``gcs``
+     - ``gcs://bucket-name/prefix/``
+     - Google Cloud Storage
+
+Welche Protokolle aktiv sind, steht in ``crawler.file.protocols``; der Standardwert ist ``file,smb,smb1,ftp,s3,gcs``.
+
+Für Windows-Dateifreigaben ist normalerweise ``smb`` die richtige Wahl. ``smb1`` bleibt für alte NAS-Geräte und Druckserver erhalten, die nichts anderes können; SMB1 ist in Windows aus Sicherheitsgründen standardmäßig deaktiviert und daher für eine neue Installation keine Option.
+
+Bestehende Zugriffsrechte bleiben erhalten
+==========================================
+
+Die größte Sorge bei einer Suche über einen Dateiserver ist, dass Dokumente in den Treffern auftauchen, die jemand nicht sehen darf. Erscheinen die Ordner von Personal und Buchhaltung bei allen, ist das Suchsystem unbrauchbar, wie gut das Ranking auch sein mag.
+
+Fess löst das, indem es **die Zugriffsrechte des Dateiservers selbst in die Suche übernimmt**.
+
+Funktionsweise
+--------------
+
+1. Beim Crawlen liest Fess die ACL jeder Datei
+2. Die erlaubten und die verweigerten Konten und Gruppen werden als Rollen des Dokuments gespeichert
+3. Bei der Suche werden diese Rollen mit denen des angemeldeten Benutzers abgeglichen, und nur zulässige Dokumente kommen zurück
+
+Sowohl Erlauben als auch Verweigern wird behandelt, intern unterschieden durch die Präfixe ``(allow)`` und ``(deny)``. Das Auslesen der Rollen aus der ACL ist standardmäßig aktiv.
+
+.. list-table:: Einstellungen für die Übernahme der Rechte
+   :header-rows: 1
+   :widths: 38 14 48
+
+   * - Einstellung
+     - Standard
+     - Wirkung
+   * - ``smb.role.from.file``
+     - ``true``
+     - Übernimmt Rollen aus der ACL von über SMB gecrawlten Dateien
+   * - ``file.role.from.file``
+     - ``true``
+     - Übernimmt Rollen aus den Rechten des lokalen Dateisystems
+   * - ``ftp.role.from.file``
+     - ``true``
+     - Übernimmt Rollen aus über FTP gecrawlten Dateien
+   * - ``smb.available.sid.types``
+     - ``1,2,4:2,5:1``
+     - Welche SID-Typen zu Rollen werden; steuert die Behandlung von Benutzern und Gruppen
+
+Die Voraussetzung, die zuerst zu klären ist
+-------------------------------------------
+
+Damit das durchgängig funktioniert, **muss die suchende Person dieselben Rollen tragen**. Im Dokument steht "diese Gruppe darf mich lesen"; solange der suchende Benutzer Fess nicht mitteilen kann, in welchen Gruppen er ist, gibt es nichts abzugleichen.
+
+Damit ist **die Anbindung an Active Directory oder LDAP eine Voraussetzung** für eine rechtebewusste Suche: Fess meldet Benutzer an demselben Verzeichnis an, an dem sie auch der Dateiserver authentifiziert.
+
+Werden dagegen nur freigegebene Ordner indiziert, die im Unternehmen ohnehin alle lesen dürfen, ist die Anbindung nicht nötig. An dieser Unterscheidung entscheidet sich meist der Umfang einer ersten Einführung.
+
+Welche Dateiformate gelesen werden
+==================================
+
+Fess gewinnt den Text mit Apache Tika aus dem Dateiinhalt, sodass nicht nur der Name, sondern der Inhalt durchsuchbar ist. Genau das findet ein Dokument, an dessen Titel sich niemand mehr erinnert.
+
+Die wichtigsten Formate sind:
+
+- MS Office (doc, xls, ppt, docx, xlsx, pptx und weitere)
+- PDF
+- Reiner Text, HTML, XML
+- Rich Text (rtf)
+- Quelltext (js, c, h, java und weitere)
+- Archive (gz, tar, zip und weitere; der Inhalt wird entpackt und mit indiziert)
+
+Die vollständige Liste steht unter `Durchsuchbare Dateien <https://fess.codelibs.org/de/supported-files.html>`__.
+
+Dateien ganz ohne Text, etwa gescannte Dokumente und reine Bild-PDFs, lassen sich auf diesem Weg nicht lesen. Ob OCR nötig wird, klärt man am besten vorab an den tatsächlichen Inhalten der Zielordner.
+
+Dimensionierung und Aufbau
+==========================
+
+Fess legt seinen Index in OpenSearch ab. Kleine Installationen laufen problemlos mit Fess und OpenSearch auf demselben Rechner; wächst der Bestand, lässt sich OpenSearch als Cluster herauslösen.
+
+Für die Dimensionierung ist die reine Dateizahl ein schlechter Anhaltspunkt. Diese drei Punkte wiegen schwerer:
+
+- Die Gesamtgröße der Zielordner und welcher Anteil davon überhaupt Text enthält
+- Wie oft sich Inhalte ändern, täglich oder monatlich, denn das bestimmt den Crawl-Zeitplan
+- Die Größe einzelner Dateien, da sehr große Dateien per Konfiguration vom Crawl ausgenommen werden können
+
+Erste Schritte
+==============
+
+1. **Zuerst laufen lassen** — der `Schnellstart-Anleitung <https://fess.codelibs.org/de/quick-start.html>`__ folgen. Mit Docker Compose ist in wenigen Minuten etwas Durchsuchbares da
+2. **Crawl-Konfiguration anlegen** — Ziel-URL und Crawl-Intervall unter [Crawler] > [Dateisystem] eintragen
+3. **Zugangsdaten hinterlegen** — das Konto für die Freigabe unter [Crawler] > [Dateiauthentifizierung] eintragen
+4. **Rollen und Labels entwerfen** — Labels für die Filterung nach Abteilung, Rollen für rechteabhängige Treffer
+
+Ein durchgearbeitetes Beispiel steht in `Teil 4 Verstreute Dateien zentral durchsuchen <https://fess.codelibs.org/de/articles/guide-04.html>`__, das ein einziges Suchfeld über mehrere Dateiserver und eine Intranet-Seite aufbaut.
+
+Zusammenfassung
+===============
+
+- Fess ist ein quelloffener Suchserver, der Dateiserver über SMB/CIFS, FTP, lokale Pfade, S3 und GCS indizieren kann
+- Bei über SMB gecrawlten Dateien filtern die in der ACL hinterlegten Zugriffsrechte die Treffer, und zwar standardmäßig
+- Rechtebewusste Suche setzt die Anbindung an Active Directory oder LDAP voraus
+- Apache Tika macht den Inhalt von Office-Dokumenten und PDFs durchsuchbar
+- Klein anfangen und durch Auslagerung von OpenSearch in ein Cluster wachsen
+
+Weiterführende Hinweise
+=======================
+
+- `Crawler-Konfiguration: Web-, Dateiserver- und Datenbank-Crawling <https://fess.codelibs.org/de/stable/config/crawler-basic.html>`__
+- `Zugriffssteuerung über Rollen <https://fess.codelibs.org/de/stable/config/security-role.html>`__
+- `Durchsuchbare Dateien <https://fess.codelibs.org/de/supported-files.html>`__
+- `Schnellstart-Anleitung <https://fess.codelibs.org/de/quick-start.html>`__
+- `Administrationsleitfaden <https://fess.codelibs.org/de/stable/admin/index.html>`__

de/guide.rst

@@ -51,6 +51,7 @@ Anwendungsfaelle und Beispiele
 
 - :doc:`articles/use-cases` - Branchenspezifische und groessenabhaengige Anwendungsfaelle
 - :doc:`articles/comparison` - Fess im Vergleich zu anderen Suchloesungen (Elasticsearch, Solr usw.)
+- :doc:`articles/file-server-search` - Was vor einer Volltextsuche ueber Dateiserver zu pruefen ist
 
 .. toctree::
    :hidden:
@@ -80,3 +81,4 @@ Anwendungsfaelle und Beispiele
    articles/guide-23
    articles/use-cases
    articles/comparison
+   articles/file-server-search

en/articles/file-server-search.rst

@@ -0,0 +1,156 @@
+=============================================
+Open Source Full-Text Search for File Servers
+=============================================
+
+Introduction
+============
+
+As departments add file servers, nobody can say where a given document lives any more. Windows search works one shared folder at a time and cannot reach across servers, and a NAS with its own full-text search stops at the edge of that box.
+
+One way out is to run a full-text search server in front of the file servers. This page collects the things worth checking before you put Fess, an open source full-text search server, in that position.
+
+Who this is for
+===============
+
+- Anyone struggling to search an internal file server or NAS
+- Anyone evaluating full-text search and wondering whether open source can do the job
+- Anyone who needs to add search without disturbing existing access permissions
+
+Fess is published under the Apache License 2.0 and carries no licence fee.
+
+Where the files can live
+========================
+
+The Fess file crawler speaks the protocols below. You configure them in the admin UI under [Crawler] > [File System], as the crawl start URL.
+
+.. list-table:: Supported protocols
+   :header-rows: 1
+   :widths: 12 33 55
+
+   * - Protocol
+     - URL form
+     - Typical use
+   * - ``file``
+     - ``file:///home/share/documents/``
+     - A directory on the machine running Fess, including an already-mounted NAS
+   * - ``smb``
+     - ``smb://fileserver.example.com/share/``
+     - Windows file sharing, from SMB 2.0.2 through SMB 3.1.1
+   * - ``smb1``
+     - ``smb1://fileserver.example.com/share/``
+     - Older equipment that only speaks SMB1/CIFS
+   * - ``ftp``
+     - ``ftp://fileserver.example.com/pub/``
+     - FTP servers
+   * - ``s3``
+     - ``s3://bucket-name/prefix/``
+     - Amazon S3 and S3-compatible object storage
+   * - ``gcs``
+     - ``gcs://bucket-name/prefix/``
+     - Google Cloud Storage
+
+The enabled set is held in ``crawler.file.protocols``, which defaults to ``file,smb,smb1,ftp,s3,gcs``.
+
+For Windows file sharing you normally want ``smb``. ``smb1`` is kept for old NAS boxes and print servers that speak nothing else; SMB1 is disabled by default in Windows for security reasons, so it is not something to choose for a new deployment.
+
+Existing access permissions carry over
+======================================
+
+The biggest worry when putting search in front of a file server is that documents somebody should not see will turn up in the results. If the HR and finance folders surface for everyone, the search system is unusable no matter how good the ranking is.
+
+Fess answers this by **carrying the file server's own access permissions into search**.
+
+How it works
+------------
+
+1. While crawling, Fess reads each file's ACL
+2. The accounts and groups that are allowed or denied are recorded as that document's roles
+3. At search time those roles are matched against the roles of the signed-in user, and only permitted documents come back
+
+Both allow and deny are handled, distinguished internally by the ``(allow)`` and ``(deny)`` prefixes. Reading roles out of the ACL is enabled by default.
+
+.. list-table:: Settings that govern permission inheritance
+   :header-rows: 1
+   :widths: 38 14 48
+
+   * - Setting
+     - Default
+     - What it does
+   * - ``smb.role.from.file``
+     - ``true``
+     - Takes roles from the ACL of files crawled over SMB
+   * - ``file.role.from.file``
+     - ``true``
+     - Takes roles from local file system permissions
+   * - ``ftp.role.from.file``
+     - ``true``
+     - Takes roles from files crawled over FTP
+   * - ``smb.available.sid.types``
+     - ``1,2,4:2,5:1``
+     - Which SID types become roles; tunes how users and groups are treated
+
+The prerequisite to check first
+-------------------------------
+
+For this to work end to end, **the person searching has to carry the same roles**. The document records "this group may read me", so unless the searching user can tell Fess which groups they belong to, there is nothing to match against.
+
+That makes **integration with Active Directory or LDAP a prerequisite** for permission-aware search: Fess signs users in against the same directory the file server authenticates them with.
+
+If instead you only ever index shared folders that everyone in the company may read, the integration is not required. That distinction is usually what decides the scope of a first deployment.
+
+Which file formats can be read
+==============================
+
+Fess extracts text from file contents using Apache Tika, so the body of a document is searchable, not just its name. That is what lets somebody find a document whose title they cannot recall.
+
+The main formats are:
+
+- MS Office (doc, xls, ppt, docx, xlsx, pptx and so on)
+- PDF
+- Plain text, HTML, XML
+- Rich text (rtf)
+- Source code (js, c, h, java and so on)
+- Archives (gz, tar, zip and so on; the contents are expanded and indexed too)
+
+The full list is on `Supported file types <https://fess.codelibs.org/supported-files.html>`__.
+
+Files that hold no text at all, such as scanned documents and image-only PDFs, cannot be read this way. Whether OCR is needed is worth settling by looking at what is actually in the target folders before you start.
+
+Sizing and topology
+===================
+
+Fess stores its index in OpenSearch. A small deployment runs happily with Fess and OpenSearch on the same machine, and OpenSearch can be split out into a cluster as the corpus grows.
+
+When sizing, the file count alone is a poor guide. These three matter more:
+
+- The total size of the target folders, and what share of it is text-bearing
+- How often content changes, daily or monthly, which drives the crawl schedule
+- Per-file size, since very large files can be excluded from crawling by configuration
+
+Getting started
+===============
+
+1. **Run it first** — follow `Quick Start <https://fess.codelibs.org/quick-start.html>`__. With Docker Compose you have something searchable in a few minutes
+2. **Create a crawl configuration** — register the target URL and crawl interval under [Crawler] > [File System]
+3. **Add credentials** — register the account used to reach the shared folder under [Crawler] > [File Authentication]
+4. **Design roles and labels** — labels for departmental filtering, roles for permission-based results
+
+A worked example is in `Part 4: Unified Search for Scattered Files <https://fess.codelibs.org/articles/guide-04.html>`__, which builds a single search box over several file servers and an intranet site.
+
+Summary
+=======
+
+- Fess is an open source search server that can index file servers over SMB/CIFS, FTP, local paths, S3 and GCS
+- For files crawled over SMB, the access permissions recorded in the ACL are used to filter results, and this is on by default
+- Permission-aware search requires integration with Active Directory or LDAP
+- Apache Tika makes the body of Office documents and PDFs searchable
+- Start small and grow by moving OpenSearch into a cluster
+
+References
+==========
+
+- `Crawler Configuration: Web, File Server and Database Crawling <https://fess.codelibs.org/stable/config/crawler-basic.html>`__
+- `Access Control with Roles <https://fess.codelibs.org/stable/config/security-role.html>`__
+- `Supported file types <https://fess.codelibs.org/supported-files.html>`__
+- `Quick Start <https://fess.codelibs.org/quick-start.html>`__
+- `Administration Guide <https://fess.codelibs.org/stable/admin/index.html>`__

en/guide.rst

@@ -51,6 +51,7 @@ Use Cases & Examples
 
 - :doc:`articles/use-cases` - Industry-specific and scale-based use cases
 - :doc:`articles/comparison` - Fess vs other search solutions (Elasticsearch, Solr, etc.)
+- :doc:`articles/file-server-search` - What to check before putting full-text search in front of a file server
 
 .. toctree::
    :hidden:
@@ -80,3 +81,4 @@ Use Cases & Examples
    articles/guide-23
    articles/use-cases
    articles/comparison
+   articles/file-server-search