SMB Spotlight rev 03

From Open-E Wiki
Revision as of 14:36, 22 June 2026 by Ai-B (talk | contribs) (Create SMB Spotlight (xc-elasticsearch) rev 03 Extension article)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

SMB Spotlight provides macOS Spotlight search over SMB shares by running Elasticsearch 8.8.2 as a search backend inside a self-contained LXC container. When enabled, the storage server indexes all files under the configured shares every 15 minutes using FSCrawler, and serves Spotlight search queries from Samba on port 9400. macOS clients can search by file name, metadata, and file size without building a local index — the index lives on the storage server and is available to all users of the share immediately.

Note: SMB Spotlight is delivered as an optional Small Update (the xc-elasticsearch module). This article describes revision 03. If your system was updated to a newer revision, refer to the matching Extension:SMB_Spotlight_rev_NN article.

Requirements

Before installing the Small Update, confirm that the system meets the following requirements:

  • RAM: Elasticsearch requires approximately 6 GB of RAM at runtime. Ensure that the system has sufficient free memory to accommodate this alongside normal workloads.
  • SMB with vfs_fruit: the SMB protocol must be enabled (Storage Settings → NAS Settings) and the vfs_fruit option must be active. On a cluster, this must be configured on both nodes.
  • Companion Small Update: revision 03 requires the SMB Server Small Update (the xc-samba module, revision 07 or compatible) to be installed at the same time. Both updates must be rebooted together after upload.

Installation

  1. Navigate to System Settings → Update and upload both required Small Update packages.
  2. Reboot the system. On a cluster, install the updates and reboot both nodes.
  3. After the reboot, continue with the configuration steps below.

Configuration

Step 1: Enable SMB Spotlight on the system

  1. Navigate to Storage Settings → NAS Settings and confirm that the SMB protocol is enabled with vfs_fruit active.
  2. Under Storage Settings → NAS Settings → Other settings, enable macOS Spotlight search support.
Note: enabling this option causes all files stored in the pool to be indexed by the search backend. On a cluster, this setting must be enabled on both nodes.

Step 2: Create the index dataset

On the storage pool, create a new dataset named _es_db. This dataset is used exclusively for the search index and configuration files.

Important: the _es_db dataset is excluded from indexing. Do not use it for production data. It is recommended not to create an SMB share on this dataset so that the automatically generated configuration files are not accidentally modified.

Step 3: Enable Spotlight on individual shares

For each share that should support macOS Spotlight search:

  1. Navigate to the share's options and open Protocols.
  2. If SMB is not already enabled for the share, enable it.
  3. Under Additional options, enable Enable macOS Spotlight search support.
  4. Click Apply to confirm.
Note: Spotlight search is not available for guest (password-less) share access. Users must authenticate with a password. Make sure that user access authorization is set to users with password under Share Options → Protocols, and that users are granted access under Share Options → User/group access. User accounts can be managed via LDAP or Active Directory.
Note: if Spotlight search support is disabled on a share, macOS will treat that share as if it does not support indexing. You can enable or disable Spotlight independently on each share.

Verifying the installation

Once configuration is complete, connect to the share from a macOS client using SMB and confirm that indexing is running.

From macOS

Check whether the share is being indexed: 

 mdutil -s /Volumes/<share_name>

Perform a test search: 

 mdfind -onlyin /Volumes/<share_name> <keyword>

where <share_name> is the name of your SMB share and <keyword> is a word appearing in a file name or file content.

From the storage server

The indexing status can be checked using a web browser by navigating to: 

 http://<server_ip>:9400/_cat/indices?v

This shows the Elasticsearch index list with document counts and size. The index is named pools_job.

Log files

Log files from the indexer and Elasticsearch are stored on the _es_db dataset. The most relevant logs are:

  • fscrawler_unit.log — result of each indexing run (lines about SLF4J can be ignored)
  • fscrawler.log — file scanning activity
  • elasticsearch.log — Elasticsearch service log
Note: these log files are not included in the diagnostic package downloaded from the GUI.

How it works

  • The SMB service creates a control flag when macOS Spotlight search support is enabled.
  • The Elasticsearch container detects the flag and starts the Elasticsearch service and the FSCrawler indexer.
  • FSCrawler crawls all files under /Pools every 15 minutes and indexes file metadata (name, size, timestamps) into Elasticsearch. File content is not indexed in this revision.
  • When a macOS client performs a Spotlight search on a share, Samba queries Elasticsearch on port 9400 and returns matching results.
  • When macOS Spotlight search support is disabled, the container stops both services automatically.

Known issues and limitations

  • Content indexing not available. This revision indexes file metadata only (name, size, modification date). Full-text content search (searching inside document text) is not supported.
  • Guest access not supported. Spotlight search requires authenticated user access. Shares configured for guest (anonymous) access cannot use Spotlight.
  • Index not included in GUI diagnostic download. The log files generated by Elasticsearch and FSCrawler are stored in the _es_db dataset and are not collected in the standard diagnostic package available from the GUI.
  • Memory requirement. Elasticsearch requires approximately 6 GB of RAM. On systems with limited RAM, enabling this extension may impact overall system performance.
  • Cluster: all configuration steps (SMB with vfs_fruit, Spotlight system option, dataset creation, share options) must be applied on both nodes of a cluster. After a failover, the Elasticsearch container starts automatically on the active node and indexing resumes.

Changelog

rev 03

  • Container rebased on Debian 12 (bookworm)
  • Elasticsearch 8.8.2 with FSCrawler 2.10 for file metadata indexing
  • Automatic start/stop controlled by Samba spotlight flag
  • 15-minute indexing interval across all pools
  • Index stored on dedicated _es_db ZFS dataset
  • Samba queries Elasticsearch on port 9400 (127.0.0.1)

For further customization or troubleshooting, refer to the upstream Elasticsearch documentation or contact Open-E support.

Retrieved from "https://wiki.open-e.com/default/wiki/index.php?title=Extension:SMB_Spotlight_rev_03&oldid=12427"