<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<appendix>
  <title>Sphinx manpages</title>

  <refentry id="indexer">
    <refmeta>
      <refentrytitle>indexer</refentrytitle>

      <manvolnum>1</manvolnum>

      <refmiscinfo class="manual">Sphinxsearch</refmiscinfo>

      <refmiscinfo class="version">2.2.11-release</refmiscinfo>
    </refmeta>

    <refnamediv>
      <refname>indexer</refname>

      <refpurpose>Sphinxsearch fulltext index generator</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
        <command>indexer</command>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <arg choice="opt">--rotate</arg>

        <group choice="opt">
          <arg choice="plain">--noprogress</arg>

          <arg choice="plain">--quiet</arg>
        </group>

        <group choice="opt">
          <arg choice="plain">--all</arg>

          <arg choice="plain"><replaceable>INDEX</replaceable></arg>

          <arg choice="plain"><replaceable>...</replaceable></arg>
        </group>
      </cmdsynopsis>

      <cmdsynopsis>
        <command>indexer</command>

        <arg choice="plain">--buildstops
        <replaceable>OUTPUTFILE</replaceable></arg>

        <arg choice="plain"><replaceable>COUNT</replaceable></arg>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <group choice="opt">
          <arg choice="plain">--noprogress</arg>

          <arg choice="plain">--quiet</arg>
        </group>

        <group choice="opt">
          <arg choice="plain">--all</arg>

          <arg choice="plain"><replaceable>INDEX</replaceable></arg>

          <arg choice="plain"><replaceable>...</replaceable></arg>
        </group>
      </cmdsynopsis>

      <cmdsynopsis>
        <command>indexer</command>

        <arg choice="plain">--merge
        <replaceable>MAIN_INDEX</replaceable></arg>

        <arg choice="plain"><replaceable>DELTA_INDEX</replaceable></arg>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <arg choice="opt">--rotate</arg>

        <group choice="opt">
          <arg choice="plain">--noprogress</arg>

          <arg choice="plain">--quiet</arg>
        </group>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>Sphinx is a collection of programs that aim to provide high
      quality fulltext search.</para>

      <para><command>indexer</command> is the first of the two principle tools
      as part of Sphinx. Invoked from either the command line directly, or as
      part of a larger script, <command>indexer</command> is solely
      responsible for gathering the data that will be searchable.</para>

      <para>The calling syntax for indexer is as follows:</para>

      <programlisting>$ indexer [OPTIONS] [indexname1 [indexname2 [...]]]</programlisting>

      <para>Essentially you would list the different possible indexes (that
      you would later make available to search) in
      <filename>sphinx.conf</filename>, so when calling
      <command>indexer</command>, as a minimum you need to be telling it what
      index (or indexes) you want to index.</para>

      <para>If <filename>sphinx.conf</filename> contained details on 2
      indexes, <emphasis>mybigindex</emphasis> and
      <emphasis>mysmallindex</emphasis>, you could do the following:</para>

      <programlisting>$ indexer mybigindex
$ indexer mysmallindex mybigindex</programlisting>

      <para>As part of the configuration file,
      <filename>sphinx.conf</filename>, you specify one or more indexes for
      your data. You might call <command>indexer</command> to reindex one of
      them, ad-hoc, or you can tell it to process all indexes - you are not
      limited to calling just one, or all at once, you can always pick some
      combination of the available indexes.</para>
    </refsect1>

    <refsect1>
      <title>Options</title>

      <para>The majority of the options for <command>indexer</command> are
      given in the configuration file, however there are some options you
      might need to specify on the command line as well, as they can affect
      how the indexing operation is performed. These options are:</para>

      <variablelist remap="IP">
        <varlistentry>
          <term><option>--all</option></term>

          <listitem>
            <para>Tells <command>indexer</command> to update every index
            listed in <filename>sphinx.conf</filename>, instead of listing
            individual indexes. This would be useful in small configurations,
            or cron-type or maintenance jobs where the entire index set will
            get rebuilt each day, or week, or whatever period is best.</para>

            <para>Example usage:</para>

            <programlisting>$ indexer --config /home/myuser/sphinx.conf --all</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--buildstops</option>
          <replaceable>outfile.txt</replaceable>
          <replaceable>NUM</replaceable></term>

          <listitem>
            <para>Reviews the index source, as if it were indexing the data,
            and produces a list of the terms that are being indexed. In other
            words, it produces a list of all the searchable terms that are
            becoming part of the index. Note; it does not update the index in
            question, it simply processes the data 'as if' it were indexing,
            including running queries defined with
            <emphasis>sql_query_pre</emphasis> or
            <emphasis>sql_query_post</emphasis>.
            <filename>outputfile.txt</filename> will contain the list of
            words, one per line, sorted by frequency with most frequent first,
            and <emphasis>NUM</emphasis> specifies the maximum number of words
            that will be listed; if sufficiently large to encompass every word
            in the index, only that many words will be returned. Such a
            dictionary list could be used for client application features
            around "Did you mean..." functionality, usually in conjunction
            with <option>--buildfreqs</option>, below.</para>

            <para>Example:</para>

            <programlisting>$ indexer myindex --buildstops word_freq.txt 1000</programlisting>

            <para>This would produce a document in the current directory,
            <filename>word_freq.txt</filename> with the 1,000 most common
            words in 'myindex', ordered by most common first. Note that the
            file will pertain to the last index indexed when specified with
            multiple indexes or <option>--all</option> (i.e. the last one
            listed in the configuration file)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--buildfreqs</option></term>

          <listitem>
            <para>Used in pair with <option>--buildstops</option> (and is
            ignored if <option>--buildstops</option> is not specified). As
            <option>--buildstops</option> provides the list of words used
            within the index, <option>--buildfreqs</option> adds the quantity
            present in the index, which would be useful in establishing
            whether certain words should be considered stopwords if they are
            too prevalent. It will also help with developing "Did you mean..."
            features where you can how much more common a given word compared
            to another, similar one.</para>

            <para>Example:</para>

            <programlisting>$ indexer myindex --buildstops word_freq.txt 1000 --buildfreqs</programlisting>

            <para>This would produce the <filename>word_freq.txt</filename> as
            above, however after each word would be the number of times it
            occurred in the index in question.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--config</option> <replaceable>CONFIGRILE</replaceable>,
          <option>-c</option> <replaceable>CONFIGFILE</replaceable></term>

          <listitem>
            <para>Use the given file as configuration. Normally, it will look
            for <filename>sphinx.conf</filename> in the installation directory
            (e.g.<filename> /usr/local/sphinx/etc/sphinx.conf</filename> if
            installed into <filename>/usr/local/sphinx</filename>), followed
            by the current directory you are in when calling indexer from the
            shell. This is most of use in shared environments where the binary
            files are installed somewhere like
            <filename>/usr/local/sphinx/</filename> but you want to provide
            users with the ability to make their own custom Sphinx set-ups, or
            if you want to run multiple instances on a single server. In cases
            like those you could allow them to create their own
            <filename>sphinx.conf</filename> files and pass them to
            <command>indexer</command> with this option.</para>

            <para>For example:</para>

            <programlisting>$ indexer --config /home/myuser/sphinx.conf myindex</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dump-rows</option>
          <replaceable>FILE</replaceable></term>

          <listitem>
            <para>Dumps rows fetched by SQL source(s) into the specified file,
            in a MySQL compatible syntax. Resulting dumps are the exact
            representation of data as received by indexer and help to repeat
            indexing-time issues.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--merge</option> <replaceable>DST-INDEX</replaceable>
          <replaceable>SRC-INDEX</replaceable></term>

          <listitem>
            <para>Physically merge together two indexes. For example if you
            have a main+delta scheme, where the main index rarely changes, but
            the delta index is rebuilt frequently, and
            <option>--merge</option> would be used to combine the two. The
            operation moves from right to left - the contents of
            <replaceable>SRC-INDEX</replaceable> get examined and physically
            combined with the contents of <replaceable>DST-INDEX</replaceable>
            and the result is left in <replaceable>DST-INDEX</replaceable>. In
            pseudo-code, it might be expressed as:
            <replaceable>DST-INDEX</replaceable> +=
            <replaceable>SRC-INDEX</replaceable></para>

            <para>An example:</para>

            <programlisting>$ indexer --merge main delta --rotate</programlisting>

            <para>In the above example, where the main is the master, rarely
            modified index, and delta is the less frequently modified one, you
            might use the above to call <command>indexer</command> to combine
            the contents of the delta into the main index and rotate the
            indexes.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--merge-dst-range</option>
          <replaceable>ATTR</replaceable> <replaceable>MIN</replaceable>
          <replaceable>MAX</replaceable></term>

          <listitem>
            <para>Run the filter range given upon merging. Specifically, as
            the merge is applied to the destination index (as part of
            <option>--merge</option>, and is ignored if
            <option>--merge</option> is not specified),
            <command>indexer</command> will also filter the documents ending
            up in the destination index, and only documents will pass through
            the filter given will end up in the final index. This could be
            used for example, in an index where there is a 'deleted'
            attribute, where 0 means 'not deleted'. Such an index could be
            merged with:<programlisting>$ indexer --merge main delta --merge-dst-range deleted 0 0</programlisting></para>

            <para>Any documents marked as deleted (value 1) would be removed
            from the newly-merged destination index. It can be added several
            times to the command line, to add successive filters to the merge,
            all of which must be met in order for a document to become part of
            the final index.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--merge-killlists</option>,
          <option>--merge-klists</option></term>

          <listitem>
            <para>Used in pair with <option>--merge</option>. Usually when
            merging <command>indexer</command> uses kill-list of source index
            (i.e., the one which is merged into) as the filter to wipe out the
            matching docs from the destination index. At the same time the
            kill-list of the destination itself isn't touched at all. When
            using <option>--merge-killlists</option>, (or it shorter form
            <option>--merge-klists</option>) the <command>indexer</command>
            will not filter the dst-index docs with src-index killlist, but it
            will merge their kill-lists together, so the final result index
            will have the kill-list containing the merged source
            kill-lists.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--noprogress</option></term>

          <listitem>
            <para>Don't display progress details as they occur; instead, the
            final status details (such as documents indexed, speed of indexing
            and so on are only reported at completion of indexing. In
            instances where the script is not being run on a console (or
            'tty'), this will be on by default.</para>

            <para>Example usage:</para>

            <programlisting>$ indexer --rotate --all --noprogress</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--print-queries</option></term>

          <listitem>
            <para>Prints out SQL queries that indexer sends to the database,
            along with SQL connection and disconnection events. That is useful
            to diagnose and fix problems with SQL sources.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option></term>

          <listitem>
            <para>Tells <command>indexer</command> not to output anything,
            unless there is an error. Again, most used for cron-type, or other
            script jobs where the output is irrelevant or unnecessary, except
            in the event of some kind of error.</para>

            <para>Example usage:</para>

            <programlisting>$ indexer --rotate --all --quiet</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rotate</option></term>

          <listitem>
            <para>Used for rotating indexes. Unless you have the situation
            where you can take the search function offline without troubling
            users, you will almost certainly need to keep search running
            whilst indexing new documents. <option>--rotate</option> creates a
            second index, parallel to the first (in the same place, simply
            including <filename>.new</filename> in the filenames). Once
            complete, <command>indexer</command> notifies
            <command>searchd</command> via sending the
            <emphasis>SIGHUP</emphasis> signal, and <command>searchd</command>
            will attempt to rename the indexes (renaming the existing ones to
            include <filename>.old</filename> and renaming the
            <filename>.new</filename> to replace them), and then start serving
            from the newer files. Depending on the setting of
            <option>seamless_rotate</option>, there may be a slight delay in
            being able to search the newer indexes.</para>

            <para>Example usage:</para>

            <programlisting>$ indexer --rotate --all</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--sighup-each</option></term>

          <listitem>
            <para>is useful when you are rebuilding many big indexes, and want
            each one rotated into <command>searchd</command> as soon as
            possible. With <option>--sighup-each</option>,
            <command>indexer</command> will send a <emphasis>SIGHUP</emphasis>
            signal to <command>searchd</command> after succesfully completing
            the work on each index. (The default behavior is to send a single
            <emphasis>SIGHUP</emphasis> after all the indexes were
            built.)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--verbose</option></term>

          <listitem>
            <para>Guarantees that every row that caused problems indexing
            (duplicate, zero, or missing document ID; or file field IO issues;
            etc) will be reported. By default, this option is off, and problem
            summaries may be reported instead.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Author</title>

      <para>Andrey Aksenoff (<email>shodan@sphinxsearch.com</email>). This
      manual page is written by Alexey Vinogradov
      (<email>klirichek@sphinxsearch.com</email>), using the one written by
      Christian Hofstaedtler ch+debian-packages@zeha.at for the <emphasis
      remap="B">Debian</emphasis> system (but may be used by others).
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU General Public License, Version 2 any later
      version published by the Free Software Foundation.</para>

      <para>On Debian systems, the complete text of the GNU General Public
      License can be found in
      <filename>/usr/share/common-licenses/GPL</filename>.</para>
    </refsect1>

    <refsect1>
      <title>See also</title>

      <para><citerefentry>
          <refentrytitle>searchd</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>search</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>indextool</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>spelldump</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry></para>

      <para id="docref">Sphinx and it's programs are documented fully by the
      <emphasis remap="I">Sphinx reference manual</emphasis> available in
      <filename>/usr/share/doc/sphinxsearch</filename>.</para>
    </refsect1>
  </refentry>

  <refentry id="searchd">
    <refmeta>
      <refentrytitle>searchd</refentrytitle>

      <manvolnum>1</manvolnum>

      <refmiscinfo class="manual">Sphinxsearch</refmiscinfo>

      <refmiscinfo class="version">2.2.11-release</refmiscinfo>
    </refmeta>

    <refnamediv>
      <refname>searchd</refname>

      <refpurpose>Sphinxsearch network daemon.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
        <command>searchd</command>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <arg choice="opt">--cpustats</arg>

        <arg choice="opt">--iostats</arg>

        <arg choice="opt">--index <replaceable>INDEX</replaceable></arg>

        <arg choice="opt">--port <replaceable>PORT</replaceable></arg>
      </cmdsynopsis>

      <cmdsynopsis>
        <command>searchd</command>

        <arg choice="plain">--status</arg>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <arg choice="opt">--pidfile <replaceable>PIDFILE</replaceable></arg>
      </cmdsynopsis>

      <cmdsynopsis>
        <command>searchd</command>

        <arg choice="plain">--stop</arg>

        <arg choice="opt">--config <replaceable>CONFIGFILE</replaceable></arg>

        <arg choice="opt">--pidfile <replaceable>PIDFILE</replaceable></arg>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>Sphinx is a collection of programs that aim to provide high
      quality fulltext search.</para>

      <para>Searchd is the second of the two principle tools as part of
      Sphinx. <command>searchd</command> is the part of the system which
      actually handles searches; it functions as a server and is responsible
      for receiving queries, processing them and returning a dataset back to
      the different APIs for client applications.</para>

      <para>Unlike <command>indexer</command>, <command>searchd</command> is
      not designed to be run either from a regular script or command-line
      calling, but instead either as a daemon to be called from
      <emphasis>init.d</emphasis> (on Unix/Linux type systems) or to be called
      as a service (on Windows-type systems). so not all of the command line
      options will always apply, and so will be build-dependent.</para>
    </refsect1>

    <refsect1>
      <title>Options</title>

      <para>These programs follow the usual GNU command line syntax, with long
      options starting with two dashes (`-').</para>

      <para>The options available to searchd on all builds are:</para>

      <variablelist remap="IP">
        <varlistentry>
          <term><option>--config</option><replaceable>CONFIGFILE</replaceable>,
          <option>-c</option><replaceable>CONFIGFILE</replaceable></term>

          <listitem>
            <para>Tell <command>searchd</command> to use the given file as its
            configuration, just as with <command>indexer</command>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--console</option></term>

          <listitem>
            <para>Force <command>searchd</command> into console mode;
            typically it will be running as a conventional server application,
            and will aim to dump information into the log files (as specified
            in <filename>sphinx.conf</filename>). Sometimes though, when
            debugging issues in the configuration or the daemon itself, or
            trying to diagnose hard-to-track-down problems, it may be easier
            to force it to dump information directly to the console/command
            line from which it is being called. Running in console mode also
            means that the process will not be forked (so searches are done in
            sequence) and logs will not be written to. (It should be noted
            that console mode is not the intended method for running
            searchd.)</para>

            <para>You can invoke it as such:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --console</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--cpustats</option></term>

          <listitem>
            <para>Used to provide actual CPU time report (in addition to wall
            time) in both query log file (for every given query) and status
            report (aggregated). It depends on
            <emphasis>clock_gettime()</emphasis> system call and might
            therefore be unavailable on certain systems.</para>

            <para>You might start searchd thus:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --cpustats</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--help</option>, <option>-h</option>,
          <option>--?</option>, <option>-?</option></term>

          <listitem>
            <para>List all of the parameters that can be called in your
            particular build of <command>searchd</command>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--index</option> <replaceable>INDEX</replaceable>,
          <option>-i</option> <replaceable>INDEX</replaceable></term>

          <listitem>
            <para>Serve only the specified index. Like
            <option>--port</option>, this is usually for debugging purposes;
            more long-term changes would generally be applied to the
            configuration file itself.</para>

            <para>Usage example:</para>

            <programlisting>$ searchd --index myindex</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--iostats</option></term>

          <listitem>
            <para>Used in conjuction with the logging options (the
            <option>query_log</option> will need to have been activated in
            <filename>sphinx.conf</filename>) to provide more detailed
            information on a per-query basis as to the input/output operations
            carried out in the course of that query, with a slight performance
            hit and of course bigger logs. Further details are available under
            the query log format section.</para>

            <para>You might start searchd thus:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --iostats</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listen</option>, <option>-l</option> <replaceable>(
          address ":" port | port | path ) [ ":" protocol
          ]</replaceable></term>

          <listitem>
            <para>Works as <option>--port</option>, but allow you to specify
            not only the port, but full path, as IP address and port, or
            Unix-domain socket path, that <command>searchd</command> will
            listen on. Otherwords, you can specify either an IP address (or
            hostname) and port number, or just a port number, or Unix socket
            path. If you specify port number but not the address, searchd will
            listen on all network interfaces. Unix path is identified by a
            leading slash. As the last param you can also specify a protocol
            handler (listener) to be used for connections on this socket.
            Supported protocol values are 'sphinx' (Sphinx 0.9.x API protocol)
            and 'mysql41' (MySQL protocol used since 4.1 upto at least
            5.1).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--logdebug, --logdebugv, --logdebugvv</option></term>

          <listitem>
            <para>Enable additional debug output in the daemon log. Should
            only be needed rarely, to assist with debugging issues that could
            not be easily reproduced on request. <option>--logdebug</option>
            causes daemon to fire general debug messages.
            <option>--logdebugv</option> and <option>--logdebugvv</option>
            points to 'verbose' and 'very verbose' debug info. The last could
            really flood your logfile.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--nodetach</option></term>

          <listitem>
            <para>Do not 'daemonize', or, do not detach into background. Apart
            debug purposes, this switch is useful when you manage sphinx with
            upstart init daemon. In this case actual 'daemonizing' will be
            done by upstart itself, and also all tasks like starting,
            stopping, reloading the config and respawning on crash will be
            done by the system, not the sphinx.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pidfile</option>
          <replaceable>PIDFILE</replaceable></term>

          <listitem>
            <para>Explicitly state a PID file, where the process information
            is stored regarding <command>searchd</command>, used for
            inter-process communications (for example,
            <command>indexer</command> will need to know the PID to contact
            <command>searchd</command> for rotating indexes). Normally,
            <command>searchd</command> would use a PID if running in regular
            mode (i.e. not with <option>--console</option>), but it is
            possible that you will be running it in console mode whilst the
            index is being updated and rotated, for which a PID file will be
            needed.</para>

            <para>Example:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --pidfile /home/myuser/sphinx.pid</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--replay-flags</option> <replaceable>OPTIONS</replaceable></term>

          <listitem>
            <para>Specify a list of extra binary log replay options. The
            supported options are:<itemizedlist>
                <listitem>
                  <para><option>accept-desc-timestamp</option>, ignore
                  descending transaction timestamps and replay such
                  transactions anyway (the default behavior is to exit with an
                  error).</para>
                </listitem>
              </itemizedlist></para>

            <para>Example:</para>

            <programlisting>$ searchd --replay-flags=accept-desc-timestamp</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--port</option> <replaceable>PORT</replaceable>,
          <option>-p</option> <replaceable>PORT</replaceable></term>

          <listitem>
            <para>Specify the <emphasis>port</emphasis> that
            <command>searchd</command> should listen on, usually for debugging
            purposes. This will usually default to <option>9312</option>, but
            sometimes you need to run it on a different port. Specifying it on
            the command line will override anything specified in the
            configuration file. The valid range is 0 to 65535, but ports
            numbered 1024 and below usually require a privileged account in
            order to run. Look also the <option>--listen</option> option, it
            will give you more possibilities to tune here.</para>

            <para>An example of usage:</para>

            <programlisting>$ searchd --port 9313</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--safetrace</option></term>

          <listitem>
            <para>Forces <command>searchd</command> to only use system backtrace()
            call in crash reports. In certain (rare) scenarios, this might be
            a "safer" way to get that report. This is a debugging option.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--status</option></term>

          <listitem>
            <para>Query running <command>searchd</command> instance status,
            using the connection details from the (optionally) provided
            configuration file. It will try to connect to the running instance
            using the first configured UNIX socket or TCP port. On success, it
            will query for a number of status and performance counter values
            and print them. You can use <emphasis>Status()</emphasis> API call
            to access the very same counters from your application.</para>

            <para>Examples:</para>

            <programlisting>$ searchd --status
$ searchd --config /home/myuser/sphinx.conf --status</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--stop</option></term>

          <listitem>
            <para>Asynchronously stop <command>searchd</command>, using the
            details of the PID file as specified in the
            <filename>sphinx.conf</filename> file, so you may also need to
            confirm to <command>searchd</command> which configuration file to
            use with the <option>--config</option> option. NB, calling
            <option>--stop</option> will also make sure any changes applied to
            the indexes with <emphasis>UpdateAttributes()</emphasis> will be
            applied to the index files themselves.</para>

            <para>Example:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --stop</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--stopwait</option></term>

          <listitem>
            <para>Synchronously stop <command>searchd</command>.
            <option>--stop</option> essentially tells the running instance to
            exit (by sending it a <emphasis>SIGTERM</emphasis>) and then
            immediately returns. <option>--stopwait</option> will also attempt
            to wait until the running <command>searchd</command> instance
            actually finishes the shutdown (eg. saves all the pending
            attribute changes) and exits.</para>

            <para>Example:</para>

            <programlisting>$ searchd --config /home/myuser/sphinx.conf --stopwait</programlisting>

            <para>Possible exit codes are as follows:</para>

            <itemizedlist>
              <listitem>
                <para>0 on success;</para>
              </listitem>

              <listitem>
                <para>1 if connection to running <command>searchd</command>
                daemon failed;</para>
              </listitem>

              <listitem>
                <para>2 if daemon reported an error during shutdown;</para>
              </listitem>

              <listitem>
                <para>3 if daemon crashed during shutdown</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--strip-path</option></term>

          <listitem>
            <para>Strip the path names from all the file names referenced from
            the index (<emphasis>stopwords</emphasis>,
            <emphasis>wordforms</emphasis>, <emphasis>exceptions</emphasis>,
            etc). This is useful for picking up indexes built on another
            machine with possibly different path layouts.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Signals</title>

      <para>Last but not least, as every other daemon,
      <command>searchd</command> supports a number of signals.</para>

      <para><variablelist>
          <varlistentry>
            <term>SIGTERM</term>

            <listitem>
              <para>Initiates a clean shutdown. New queries will not be
              handled; but queries that are already started will not be
              forcibly interrupted.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SIGHUP</term>

            <listitem>
              <para>Initiates index rotation. Depending on the value of
              <option>seamless_rotate</option> setting, new queries might be
              shortly stalled; clients will receive temporary errors.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SIGUSR1</term>

            <listitem>
              <para>Forces reopen of searchd log and query log files, letting
              you implement log file rotation.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>
    </refsect1>

    <refsect1>
      <title>Author</title>

      <para>Andrey Aksenoff (<email>shodan@sphinxsearch.com</email>). This
      manual page is written by Alexey Vinogradov
      (<email>klirichek@sphinxsearch.com</email>), using the one written by
      Christian Hofstaedtler ch+debian-packages@zeha.at for the <emphasis
      remap="B">Debian</emphasis> system (but may be used by others).
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU General Public License, Version 2 any later
      version published by the Free Software Foundation.</para>

      <para>On Debian systems, the complete text of the GNU General Public
      License can be found in
      <filename>/usr/share/common-licenses/GPL</filename>.</para>
    </refsect1>

    <refsect1>
      <title>See also</title>

      <para><citerefentry>
          <refentrytitle>indexer</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>search</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>indextool</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry></para>

      <para>Sphinx and it's programs are documented fully by the <emphasis
      remap="I">Sphinx reference manual</emphasis> available in
      <filename>/usr/share/doc/sphinxsearch</filename>.</para>
    </refsect1>
  </refentry>

  <refentry id="spelldump">
    <refmeta>
      <refentrytitle>spelldump</refentrytitle>

      <manvolnum>1</manvolnum>

      <refmiscinfo class="manual">Sphinxsearch</refmiscinfo>

      <refmiscinfo class="version">2.2.11-release</refmiscinfo>
    </refmeta>

    <refnamediv>
      <refname>spelldump</refname>

      <refpurpose>Sphinxsearch tool for extract the contents of a dictionary
      file.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
        <command>spelldump</command>

        <arg choice="opt">OPTIONS</arg>

        <arg choice="plain">dictionary</arg>

        <arg choice="plain">affix</arg>

        <arg>result</arg>

        <arg>locale-name</arg>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>Sphinx is a collection of programs that aim to provide high
      quality fulltext search.</para>

      <para>spelldump is used to extract the contents of a dictionary file
      that uses ispell or MySpell format, which can help build word lists for
      wordforms - all of the possible forms are pre-built for you.</para>

      <para>The two main parameters are the dictionary's main file and its
      affix file; usually these are named as
      <filename>[language-prefix].dict</filename> and
      <filename>[language-prefix].aff</filename> and will be available with
      most common Linux distributions, as well as various places online.
      <option>[result]</option> specifies where the dictionary data should be
      output to, and <option>[locale-name]</option> additionally specifies the
      locale details you wish to use.</para>

      <para>Examples of its usage are:</para>

      <para><programlisting>spelldump en.dict en.aff
spelldump ru.dict ru.aff ru.txt ru_RU.CP1251
spelldump ru.dict ru.aff ru.txt .1251</programlisting></para>

      <para>The results file will contain a list of all the words in the
      dictionary in alphabetical order, output in the format of a wordforms
      file, which you can use to customise for your specific
      circumstances.</para>

      <para>An example of the result file:</para>

      <para><programlisting>zone &gt; zone
zoned &gt; zoned
zoning &gt; zoning </programlisting></para>
    </refsect1>

    <refsect1>
      <title>Options</title>

      <variablelist remap="IP">
        <varlistentry>
          <term><option>-c</option> <replaceable>[FILE]</replaceable></term>

          <listitem>
            <para>specifies a file for case conversion details.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Author</title>

      <para>Andrey Aksenoff (<email>shodan@sphinxsearch.com</email>). This
      manual page is written by Alexey Vinogradov
      (<email>klirichek@sphinxsearch.com</email>). Permission is granted to
      copy, distribute and/or modify this document under the terms of the GNU
      General Public License, Version 2 any later version published by the
      Free Software Foundation.</para>

      <para>On Debian systems, the complete text of the GNU General Public
      License can be found in
      <filename>/usr/share/common-licenses/GPL</filename>.</para>
    </refsect1>

    <refsect1>
      <title>See also</title>

      <para><citerefentry>
          <refentrytitle>indexer</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>indextool</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>.</para>

      <para>Sphinx and it's programs are documented fully by the <emphasis
      remap="I">Sphinx reference manual</emphasis> available in
      <filename>/usr/share/doc/sphinxsearch</filename>.</para>
    </refsect1>
  </refentry>

  <refentry id="indextool">
    <refmeta>
      <refentrytitle>indextool</refentrytitle>

      <manvolnum>1</manvolnum>

      <refmiscinfo class="manual">Sphinxsearch</refmiscinfo>

      <refmiscinfo class="version">2.2.11-release</refmiscinfo>
    </refmeta>

    <refnamediv>
      <refname>indextool</refname>

      <refpurpose>Sphinxsearch tool dump miscellaneous debug information about
      the physical index.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
        <command>indextool</command>

        <arg choice="req">command</arg>

        <arg>options</arg>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>Sphinx is a collection of programs that aim to provide high
      quality fulltext search.</para>

      <para><command>indextool</command> is one of the helper tools within the
      Sphinx package. It is used to dump miscellaneous debug information about
      the physical index. Apart ghe dumping <command>indextool</command> can
      perform index verification, hence the indextool name rather than just
      indexdump.</para>
    </refsect1>

    <refsect1>
      <title>Commands</title>

      <para>The commands are as follows:</para>

      <variablelist>
        <varlistentry>
          <term><option>--dumpheader</option>
          <replaceable>FILENAME.sph</replaceable></term>

          <listitem>
            <para>quickly dumps the provided index header file without
            touching any other index files or even the configuration file. The
            report provides a breakdown of all the index settings, in
            particular the entire attribute and field list. Prior to
            0.9.9-rc2, this command was present in CLI search utility.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dumpconfig</option>
          <replaceable>FILENAME.sph</replaceable></term>

          <listitem>
            <para>dumps the index definition from the given index header file
            in (almost) compliant <filename>sphinx.conf</filename> file
            format.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dumpheader</option>
          <replaceable>INDEXNAME</replaceable></term>

          <listitem>
            <para>dumps index header by index name with looking up the header
            path in the configuration file.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dumpdocids</option>
          <replaceable>INDEXNAME</replaceable></term>

          <listitem>
            <para>dumps document IDs by index name. It takes the data from
            attribute (.spa) file and therefore requires
            <option>docinfo=extern</option> to work.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dumphitlist</option>
          <replaceable>INDEXNAME</replaceable>
          <replaceable>KEYWORD</replaceable></term>

          <listitem>
            <para>dumps all the hits (occurences) of a given keyword in a
            given index, with keyword specified as text.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dumphitlist</option>
          <replaceable>INDEXNAME</replaceable> <option>--wordid</option>
          <replaceable>ID</replaceable></term>

          <listitem>
            <para>dumps all the hits (occurences) of a given keyword in a
            given index, with keyword specified as internal numeric ID.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--htmlstrip</option> INDEXNAME</term>

          <listitem>
            <para>filters stdin using HTML stripper settings for a given
            index, and prints the filtering results to stdout. Note that the
            settings will be taken from <filename>sphinx.conf</filename>, and
            not the index header.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--check</option>
          <replaceable>INDEXNAME</replaceable></term>

          <listitem>
            <para>checks the index data files for consistency errors that
            might be introduced either by bugs in <command>indexer</command>
            and/or hardware faults.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--strip-path</option></term>

          <listitem>
            <para>strips the path names from all the file names referenced
            from the index (stopwords, wordforms, exceptions, etc). This is
            useful for checking indexes built on another machine with possibly
            different path layouts.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--optimize-rt-klists</option></term>

          <listitem>
            <para>optimizes the kill list memory use in the disk chunk of
            a given RT index. That is a one-off optimization intended for
            rather old RT indexes, created by development versions prior
            to 1.10-beta release. As of 1.10-beta releases, this kill list
            optimization (purging) should happen automatically, and there
            should never be a need to use this option.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Options</title>

      <para>The only currently available option applies to all commands and
      lets you specify the configuration file:</para>

      <variablelist remap="IP">
        <varlistentry>
          <term><option>--config</option> <replaceable>CONFIGFILE</replaceable>,
          <option>-c</option> <replaceable>CONFIGFILE</replaceable></term>

          <listitem>
            <para>overrides the built-in config file names.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Author</title>

      <para>Andrey Aksenoff (<email>shodan@sphinxsearch.com</email>). This
      manual page is written by Alexey Vinogradov
      (<email>klirichek@sphinxsearch.com</email>). Permission is granted to
      copy, distribute and/or modify this document under the terms of the GNU
      General Public License, Version 2 any later version published by the
      Free Software Foundation.</para>

      <para>On Debian systems, the complete text of the GNU General Public
      License can be found in
      <filename>/usr/share/common-licenses/GPL</filename>.</para>
    </refsect1>

    <refsect1>
      <title>See also</title>

      <para><citerefentry>
          <refentrytitle>indexer</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>searchd</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry>, <citerefentry>
          <refentrytitle>search</refentrytitle>

          <manvolnum>1</manvolnum>
        </citerefentry></para>

      <para>Sphinx and it's programs are documented fully by the <emphasis
      remap="I">Sphinx reference manual</emphasis> available in
      <filename>/usr/share/doc/sphinxsearch</filename>.</para>
    </refsect1>
  </refentry>
</appendix>