SEARCHD(1)

💖 SEARCHD(1) — the Sphinxsearch network daemon 💖

okay bestie, listen up, this is searchd, the network daemon from the Sphinxsearch fam 💅 it lives in the Sphinxsearch collection and it's the icon, the moment, the whole vibe. Let's get into it 🫶

---

✨ SYNOPSIS ✨

searchd [--config CONFIGFILE] [--cpustats] [--iostats] [--index INDEX]
        [--port PORT]

searchd --status [--config CONFIGFILE] [--pidfile PIDFILE]

searchd --stop [--config CONFIGFILE] [--pidfile PIDFILE]

---

🌸 DESCRIPTION 🌸

Sphinx is a whole collection of programs whose entire goal is providing high quality fulltext search. that's the mission. that's the point.

searchd is the second of the two principle tools in Sphinx, and honestly? she's the one actually doing the work at the party. she's the part of the system that actually handles searches — she functions as a server and is responsible for receiving queries, processing them, and returning a dataset back to the different APIs for client applications. main character energy fr fr 👑

So here's the thing, and it's lowkey important: unlike indexer, searchd is not designed to be run either from a regular script or command-line calling. instead she's meant to run either as a daemon called from init.d (on Unix/Linux type systems) or as a service (on Windows-type systems). so not all of the command line options will always apply, and so will be build-dependent. it's giving "your mileage may vary" and she said it herself, no cap.

---

🎀 OPTIONS 🎀

These programs follow the usual GNU command line syntax, with long options starting with two dashes (-).

The options available to searchd on all builds are:

• --configCONFIGFILE, -cCONFIGFILE — tell searchd to use the given file as its configuration, just as with indexer. simple as that 💖
• --console — force searchd into console mode. normally she's out here running as a conventional server application, dumping information into the log files (as specified in sphinx.conf). but sometimes, when you're debugging issues in the configuration or the daemon itself, or trying to diagnose hard-to-track-down problems, it may be easier to force her to dump information directly to the console/command line from which she's being called. running in console mode also means the process will not be forked (so searches are done in sequence) and logs will not be written to. and bestie, note this: console mode is not the intended method for running searchd. it's the debugging fit, not the everyday fit 🙈

You can invoke it as such:

$ searchd --config /home/myuser/sphinx.conf --console

• --cpustats — used to provide actual CPU time report (in addition to wall time) in both the query log file (for every given query) and the status report (aggregated). she depends on the clock_gettime() system call and might therefore be unavailable on certain systems. so if she ghosts you, that's why 😭

You might start searchd thus:

$ searchd --config /home/myuser/sphinx.conf --cpustats

• --help, -h, --?, -? — list all of the parameters that can be called in your particular build of searchd. every build is a little different, so ask your own build, she'll tell you 🦋
• --index INDEX, -i INDEX — serve only the specified index. like --port, this is usually for debugging purposes; more long-term changes would generally be applied to the configuration file itself. it's a one-index-only kinda night ✨

Usage example:

$ searchd --index myindex

• --iostats — used in conjuction with the logging options (the query_log will need to have been activated in sphinx.conf) to provide more detailed information on a per-query basis as to the input/output operations carried out in the course of that query. heads up though: this comes with a slight performance hit and of course bigger logs. further details are available under the query log format section. she's thorough but she's not free 💀

You might start searchd thus:

$ searchd --config /home/myuser/sphinx.conf --iostats

• --listen, -l ( address ":" port | port | path ) [ ":" protocol ] — works as --port, but allows you to specify not only the port, but a full path, as IP address and port, or Unix-domain socket path, that searchd will listen on. otherwords: you can specify either an IP address (or hostname) and port number, or just a port number, or a Unix socket path. if you specify a port number but not the address, searchd will listen on all network interfaces. a 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). she's flexible like that, obsessed 💅
• --logdebug, --logdebugv, --logdebugvv — 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. --logdebug causes the daemon to fire general debug messages. --logdebugv and --logdebugvv point to 'verbose' and 'very verbose' debug info. and the last one? the last could really flood your logfile. like, genuinely, be careful, that's a whole lot of yapping 🗣️
• --nodetach — do not 'daemonize', or, do not detach into background. apart from debug purposes, this switch is useful when you manage sphinx with upstart init daemon. in this case the 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. she's handing off the aux cord, it's upstart's turn now 🎧
• --pidfile PIDFILE — explicitly state a PID file, where the process information is stored regarding searchd, used for inter-process communications (for example, indexer will need to know the PID to contact searchd for rotating indexes). normally, searchd would use a PID if running in regular mode (i.e. not with --console), but it is possible that you will be running her in console mode whilst the index is being updated and rotated, for which a PID file will be needed. keep the receipts, bestie 🧾

Example:

$ searchd --config /home/myuser/sphinx.conf --pidfile /home/myuser/sphinx.pid

• --replay-flags OPTIONS — specify a list of extra binary log replay options. the supported options are:
  • accept-desc-timestamp, ignore descending transaction timestamps and replay such transactions anyway (the default behavior is to exit with an error).

Example:

$ searchd --replay-flags=accept-desc-timestamp

• --port PORT, -p PORT — specify the port that searchd should listen on, usually for debugging purposes. this will usually default to 9312, but sometimes you need to run her 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. also go look at the --listen option, it will give you more possibilities to tune here. she said check the other one too, don't be lazy ✨

An example of usage:

$ searchd --port 9313

• --safetrace — forces searchd to only use the 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. rare scenario queen 🙈
• --status — query the running searchd 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 the Status() API call to access the very same counters from your application. same numbers, different doorway 🚪

Examples:

$ searchd --status
$ searchd --config /home/myuser/sphinx.conf --status

• --stop — asynchronously stop searchd, using the details of the PID file as specified in the sphinx.conf file, so you may also need to confirm to searchd which configuration file to use with the --config option. NB, calling --stop will also make sure any changes applied to the indexes with UpdateAttributes() will be applied to the index files themselves. she's leaving but she's tidying up first 🎀

Example:

$ searchd --config /home/myuser/sphinx.conf --stop

• --stopwait — synchronously stop searchd. --stop essentially tells the running instance to exit (by sending it a SIGTERM) and then immediately returns. --stopwait will also attempt to wait until the running searchd instance actually finishes the shutdown (eg. saves all the pending attribute changes) and exits. one of them dips immediately, the other one stays until the job is done 💅

Example:

$ searchd --config /home/myuser/sphinx.conf --stopwait

Possible exit codes are as follows:

• 0 on success;
• 1 if connection to running searchd daemon failed;
• 2 if daemon reported an error during shutdown;
• 3 if daemon crashed during shutdown

• --strip-path — strip the path names from all the file names referenced from the index (stopwords, wordforms, exceptions, etc). this is useful for picking up indexes built on another machine with possibly different path layouts. she's decluttering, it's giving moving day 📦

---

🔔 SIGNALS 🔔

Last but not least, as every other daemon, searchd supports a number of signals.

• SIGTERM — initiates a clean shutdown. new queries will not be handled; but queries that are already started will not be forcibly interrupted. she's polite, she lets the current conversation finish 🫶
• SIGHUP — initiates index rotation. depending on the value of the seamless_rotate setting, new queries might be shortly stalled; clients will receive temporary errors. tiny chaos moment, it passes 😭
• SIGUSR1 — forces reopen of searchd log and query log files, letting you implement log file rotation. rotate those logs bestie 🔥

---

👑 AUTHOR 👑

Andrey Aksenoff (shodan@sphinxsearch.com). This manual page is written by Alexey Vinogradov (klirichek@sphinxsearch.com), using the one written by Christian Hofstaedtler ch+debian-packages@zeha.at for the Debian 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.

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

---

🌈 SEE ALSO 🌈

• indexer(1)
• search(1)
• indextool(1)

Sphinx and it's programs are documented fully by the Sphinx reference manual available in /usr/share/doc/sphinxsearch.

---

and that's the whole page bestie, you ate it, no crumbs 💖 this was 2.2.11-release from 07/19/2016 — go forth and serve some indexes, you've got this 🦋✨