+ <sect1>
+ <title id="spotlight">Spotlight<indexterm>
+ <primary>Spotlight</primary>
+ </indexterm></title>
+
+ <para>Starting with version 3.1 Netatalk supports Spotlight searching.
+ Netatalk uses Gnome <ulink url="https://projects.gnome.org/tracker/">Tracker</ulink> as metadata store,
+ indexer and search engine.</para>
+
+ <sect2>
+ <title>Configuration</title>
+
+ <para>You can enable Spotlight and indexing either globally or on a per
+ volume basis with the <option>spotlight</option> option.</para>
+
+ <warning>
+ <para>Once Spotlight is enable for a single volume, all other volumes
+ for which spotlight is disabled won't be searchable at all.</para>
+ </warning>
+
+ <para>In case the <command>dbus-daemon</command> binary is not installed
+ at the path <filename>/bin/dbus-daemon</filename>, you must use the
+ global option <option>dbus daemon</option> to point to the path, eg for
+ Solaris with Tracker from OpenCSW: <screen>dbus daemon = /opt/csw/bin/dbus-daemon</screen></para>
+ </sect2>
+
+ <sect2>
+ <title>Limitations and notes</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Large filesystems</para>
+
+ <para>Tracker on Linux uses the inotify Kernel filesystem change
+ event API for tracking filesystem changes. On large filesystems this
+ may be problematic since the inotify API doesn't offer recursive
+ directory watches but instead requires that for every subdirectoy
+ watches must be added individually.</para>
+
+ <para>On Solaris the FEN file event notification system is used. It
+ is unkown which limitations and ressource consumption this Solaris
+ subsystem may have.</para>
+
+ <para>We therefor recommend to disable live filesystem monitoring
+ and let Tracker periodically scan filesystems for changes instead,
+ see the Tracker configuration options <link
+ linkend="enable-monitors">enable-monitors</link> and <link
+ linkend="crawling-interval">crawling-interval</link> below.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Using Tracker commandline tools on the server</title>
+
+ <para>Netatalk must be running and the commands must be executed as
+ root:<screen>$ su
+# export DBUS_SESSION_BUS_ADDRESS="unix:path=/tmp/spotlight.ipc"</screen></para>
+
+ <para>When using Tracker from OpenCSW you must also update your
+ PATH:<screen># export PATH=/opt/csw/bin:$PATH</screen></para>
+
+ <sect3>
+ <title>Starting and stopping Tracker</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>Querying Tracker status</term>
+
+ <listitem>
+ <screen># tracker-control -S</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Stop Tracker</term>
+
+ <listitem>
+ <screen># tracker-control -t</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Start Tracker status</term>
+
+ <listitem>
+ <screen># tracker-control -s</screen>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3>
+ <title>Reindex directory</title>
+
+ <screen># tracker-control -f PATH</screen>
+ </sect3>
+
+ <sect3>
+ <title>Query Tracker for information about a file or directory</title>
+
+ <screen># tracker-info PATH</screen>
+ </sect3>
+
+ <sect3>
+ <title>Search Tracker</title>
+
+ <screen># tracker-search QUERY</screen>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Advanced Tracker command line configuration</title>
+
+ <para>Tracker stores its configuration via Gnome dconf backend which can
+ be modified with the command <command>gsettings</command>.</para>
+
+ <para>Gnome dconf settings are per-user settings, so, as Netatalk runs
+ the Tracker processes as root, the settings are stored in the root user
+ context and reading or changing these settings must be perfomed as root.
+ Netatalk must alo be running:<screen>$ su
+# export DBUS_SESSION_BUS_ADDRESS="unix:path=/tmp/spotlight.ipc"</screen></para>
+
+ <para>When using Tracker from OpenCSW you must also update your
+ PATH:<screen># export PATH=/opt/csw/bin:$PATH</screen></para>
+
+ <para><screen># gsettings list-recursively | grep Tracker
+org.freedesktop.Tracker.Writeback verbosity 'debug'
+...</screen></para>
+
+ <para>The following list describes some important Tracker options and
+ their default settings.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>org.freedesktop.Tracker.Miner.Files
+ index-recursive-directories</term>
+
+ <listitem>
+ <para>This option controls which directories Tracker will index.
+ Don't change this option manually as it is automatically set by
+ Netatalk reflecting the setting of the <option>Spotlight</option>
+ option of Netatalk volumes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term id="enable-monitors">org.freedesktop.Tracker.Miner.Files
+ enable-monitors <parameter> true</parameter></term>
+
+ <listitem>
+ <para>The value controls whether Tracker watches all configured
+ paths for modification. Depending on the filesystem modification
+ backend (FAM on Linux, FEN on Solaris), this feature may not work
+ as reliable as one might wish, so it may be safer to disable it
+ and instead rely on periodic crawling of Tracker itself. See aslo
+ the option <option>crawling-interval </option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term id="crawling-interval">org.freedesktop.Tracker.Miner.Files
+ crawling-interval <parameter>-1</parameter></term>
+
+ <listitem>
+ <para>Interval in days to check the filesystem is up to date in
+ the database, maximum is 365, default is -1. -2 = crawling is
+ disabled entirely, -1 = crawling *may* occur on startup (if not
+ cleanly shutdown), 0 = crawling is forced</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Supported metadata attributes</title>
+
+ <para>The following list is the complete set of supported metadata
+ attributes in Tracker SPARQL search queries</para>
+
+ <table>
+ <title>Tracker SPARQL</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry align="center">Description</entry>
+
+ <entry align="center">Spotlight Key</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Name</entry>
+
+ <entry>kMDItemDisplayName, kMDItemFSName</entry>
+ </row>
+
+ <row>
+ <entry>Document content (full text search)</entry>
+
+ <entry>kMDItemTextContent</entry>
+ </row>
+
+ <row>
+ <entry>File type</entry>
+
+ <entry>_kMDItemGroupId, kMDItemContentTypeTree</entry>
+ </row>
+
+ <row>
+ <entry>File modification date</entry>
+
+ <entry>kMDItemFSContentChangeDate,
+ kMDItemContentModificationDate,
+ kMDItemAttributeChangeDate</entry>
+ </row>
+
+ <row>
+ <entry>Content Creation date</entry>
+
+ <entry>kMDItemContentCreationDate</entry>
+ </row>
+
+ <row>
+ <entry>The author, or authors, of the contents of the
+ file</entry>
+
+ <entry>kMDItemAuthors, kMDItemCreator</entry>
+ </row>
+
+ <row>
+ <entry>The name of the country where the item was
+ created</entry>
+
+ <entry>kMDItemCountry</entry>
+ </row>
+
+ <row>
+ <entry>Duration</entry>
+
+ <entry>kMDItemDurationSeconds</entry>
+ </row>
+
+ <row>
+ <entry>Number of pages</entry>
+
+ <entry>kMDItemNumberOfPages</entry>
+ </row>
+
+ <row>
+ <entry>Document title</entry>
+
+ <entry>kMDItemTitle</entry>
+ </row>
+
+ <row>
+ <entry>The width, in pixels, of the contents. For example, the
+ image width or the video frame width</entry>
+
+ <entry>kMDItemPixelWidth</entry>
+ </row>
+
+ <row>
+ <entry>The height, in pixels, of the contents. For example, the
+ image height or the video frame height</entry>
+
+ <entry>kMDItemPixelHeight</entry>
+ </row>
+
+ <row>
+ <entry>The color space model used by the document
+ contents</entry>
+
+ <entry>kMDItemColorSpace</entry>
+ </row>
+
+ <row>
+ <entry>The number of bits per sample</entry>
+
+ <entry>kMDItemBitsPerSample</entry>
+ </row>
+
+ <row>
+ <entry>Focal length of the lens, in millimeters</entry>
+
+ <entry>kMDItemFocalLength</entry>
+ </row>
+
+ <row>
+ <entry>ISO speed</entry>
+
+ <entry>kMDItemISOSpeed</entry>
+ </row>
+
+ <row>
+ <entry>Orientation of the document. Possible values are 0
+ (landscape) and 1 (portrait)</entry>
+
+ <entry>kMDItemOrientation</entry>
+ </row>
+
+ <row>
+ <entry>Resolution width, in DPI</entry>
+
+ <entry>kMDItemResolutionWidthDPI</entry>
+ </row>
+
+ <row>
+ <entry>Resolution height, in DPI</entry>
+
+ <entry>kMDItemResolutionHeightDPI</entry>
+ </row>
+
+ <row>
+ <entry>Exposure time, in seconds</entry>
+
+ <entry>kMDItemExposureTimeSeconds</entry>
+ </row>
+
+ <row>
+ <entry>The composer of the music contained in the audio
+ file</entry>
+
+ <entry>kMDItemComposer</entry>
+ </row>
+
+ <row>
+ <entry>The musical genre of the song or composition</entry>
+
+ <entry>kMDItemMusicalGenre</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The following list is the complete set of supported metadata
+ attributes in Tracker RDF search queries:<table>
+ <title>Tracker RDF</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry align="center">Description</entry>
+
+ <entry align="center">Spotlight Key</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Name</entry>
+
+ <entry>kMDItemDisplayName, kMDItemFSName</entry>
+ </row>
+
+ <row>
+ <entry>Document content (full text search)</entry>
+
+ <entry>kMDItemTextContent</entry>
+ </row>
+
+ <row>
+ <entry>File type</entry>
+
+ <entry>_kMDItemGroupId, kMDItemContentTypeTree</entry>
+ </row>
+
+ <row>
+ <entry>File modification date</entry>
+
+ <entry>kMDItemFSContentChangeDate,
+ kMDItemContentModificationDate,
+ kMDItemAttributeChangeDate</entry>
+ </row>
+
+ <row>
+ <entry>Content Creation date</entry>
+
+ <entry>kMDItemContentCreationDate</entry>
+ </row>
+
+ <row>
+ <entry>The author, or authors, of the contents of the
+ file</entry>
+
+ <entry>kMDItemAuthors, kMDItemCreator</entry>
+ </row>
+
+ <row>
+ <entry>The name of the country where the item was
+ created</entry>
+
+ <entry>kMDItemCountry</entry>
+ </row>
+
+ <row>
+ <entry>Duration</entry>
+
+ <entry>kMDItemDurationSeconds</entry>
+ </row>
+
+ <row>
+ <entry>Number of pages</entry>
+
+ <entry>kMDItemNumberOfPages</entry>
+ </row>
+
+ <row>
+ <entry>Document title</entry>
+
+ <entry>kMDItemTitle</entry>
+ </row>
+
+ <row>
+ <entry>The width, in pixels, of the contents. For example, the
+ image width or the video frame width</entry>
+
+ <entry>kMDItemPixelWidth</entry>
+ </row>
+
+ <row>
+ <entry>The height, in pixels, of the contents. For example,
+ the image height or the video frame height</entry>
+
+ <entry>kMDItemPixelHeight</entry>
+ </row>
+
+ <row>
+ <entry>Focal length of the lens, in millimeters</entry>
+
+ <entry>kMDItemFocalLength</entry>
+ </row>
+
+ <row>
+ <entry>ISO speed</entry>
+
+ <entry>kMDItemISOSpeed</entry>
+ </row>
+
+ <row>
+ <entry>Orientation of the document. Possible values are 0
+ (landscape) and 1 (portrait)</entry>
+
+ <entry>kMDItemOrientation</entry>
+ </row>
+
+ <row>
+ <entry>Exposure time, in seconds</entry>
+
+ <entry>kMDItemExposureTimeSeconds</entry>
+ </row>
+
+ <row>
+ <entry>The musical genre of the song or composition</entry>
+
+ <entry>kMDItemMusicalGenre</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect2>
+
+ <sect2>
+ <title>References</title>
+
+ <orderedlist>
+ <listitem>
+ <para><ulink
+ url="https://developer.apple.com/library/mac/#documentation/Carbon/Reference/MDItemRef/Reference/reference.html">MDItem</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://live.gnome.org/Tracker/Documentation">Tracker</ulink></para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+