Operating System Linux

How to Install the Sphinx Search Engine on AlmaLinux 9 or Rocky Linux 9

Set up the Sphinx 3 full-text search server on AlmaLinux 9 or Rocky Linux 9: index a MariaDB table, query it with SphinxQL and keep searchd running with systemd.

This guide sets up the Sphinx full-text search server on AlmaLinux 9 or Rocky Linux 9 (the steps also apply to CentOS Stream 9 and RHEL 9). You will index a sample MariaDB table, query it with an ordinary MySQL client, schedule reindexing and run the search daemon under systemd. CentOS 7 reached end of life on 30 June 2024 and no longer receives updates; the RHEL 9 family replaces it.

Sphinx itself has changed since the 2.2 packages that older tutorials install. The 2.x RPMs are no longer maintained. The current series is Sphinx 3 (3.9.1, released in December 2025), which the vendor publishes as a self-contained binary tarball rather than as distribution packages or source code. If you need an open source engine with a package repository, see the section on Manticore Search near the end.

Requirements

  • AlmaLinux 9, Rocky Linux 9 or another RHEL 9 compatible system on x86-64, and a user with sudo rights. An aarch64 build of Sphinx is also published.
  • A database to index. This guide installs MariaDB from the distribution; skip that part if you already have a MySQL or MariaDB server.

Install MariaDB and create test data

Install the server, the client and the tools used later, then start the database. Sphinx's indexer loads the MySQL client library at run time under the unversioned name libmariadb.so or libmysqlclient.so; on the RHEL 9 family those names are provided by the mariadb-connector-c-devel package, so install it as well:

sudo dnf install -y mariadb-server mariadb mariadb-connector-c-devel wget tar
sudo systemctl enable --now mariadb

Create a database named test and a read-only account that Sphinx's indexer will use. Choose your own password:

sudo mariadb -e "CREATE DATABASE IF NOT EXISTS test;
CREATE USER 'sphinx'@'localhost' IDENTIFIED BY 'change-this-password';
GRANT SELECT ON test.* TO 'sphinx'@'localhost';"

Download and unpack Sphinx

The downloads page lists several Linux builds and advises picking one built against a glibc version no newer than your system's (check yours with ldd --version). The build for glibc 2.28, labelled "Centos 8 etc", meets that rule on the RHEL 9 family. Copy the current link from the downloads page if a newer release is out:

cd /tmp
wget https://sphinxsearch.com/files/sphinx-3.9.1-141d2ea-linux-amd64-glibc2.28.tar.gz
sha1sum sphinx-3.9.1-141d2ea-linux-amd64-glibc2.28.tar.gz

Compare the SHA1 value with the one printed next to the file on the downloads page. Then unpack the archive into /opt and create a dedicated system user to run it:

sudo tar -xzf sphinx-3.9.1-141d2ea-linux-amd64-glibc2.28.tar.gz -C /opt
sudo mv /opt/sphinx-3.9.1 /opt/sphinx
sudo useradd --system --home-dir /opt/sphinx --shell /sbin/nologin sphinx
sudo chown -R sphinx:sphinx /opt/sphinx

The tree contains the programs in bin/ (searchd, the search daemon, and indexer, which builds indexes from a database), the manual in doc/, and a sample configuration with matching test data in etc/.

Load the sample data and configure the index

Import the example data shipped with Sphinx. It creates two small tables, test.documents and test.tags, and drops any existing tables with those names first:

sudo mariadb test < /opt/sphinx/etc/example.sql

Copy the minimal sample configuration and open it:

sudo -u sphinx cp /opt/sphinx/etc/sphinx-min.conf.dist /opt/sphinx/etc/sphinx.conf
sudo -u sphinx vi /opt/sphinx/etc/sphinx.conf

The file has four blocks: common with the data directory, a data source, a "plain" index named test1 built from that source, and an empty real-time index named testrt. Change two things. Replace the relative data directory with an absolute path, as the Sphinx manual recommends, and set the database credentials in the source block. After editing, the first three blocks look like this (leave testrt as it is):

common
{
    datadir     = /opt/sphinx/sphinxdata
}

source src1
{
    type        = mysql

    sql_host    = localhost
    sql_user    = sphinx
    sql_pass    = change-this-password
    sql_db      = test
    sql_port    = 3306

    sql_query   = SELECT id, group_id, UNIX_TIMESTAMP(date_added) AS date_added, title, content FROM documents
}

index test1
{
    type        = plain
    source      = src1

    field       = title, content
    attr_uint   = group_id, date_added
}

Sphinx keeps everything it writes (indexes, write-ahead logs, searchd.log, the query log and its PID file) inside that data directory.

Three rules matter when you later adapt this to your own tables. The first column returned by sql_query must be a unique integer document ID. Columns named in field are full-text indexed. Columns named in attr_* directives are stored as attributes for filtering and sorting, and the column names must match the names in the index definition.

The sample has no searchd block, so the default listeners apply: port 9312 for the native SphinxAPI protocol and port 9306 for the MySQL protocol (SphinxQL), both on all network interfaces. Unless remote clients need access, add a searchd block at the end of the file that restricts both listeners to the loopback address:

searchd
{
    listen = 127.0.0.1:9312:sphinx
    listen = 127.0.0.1:9306:mysql
}

Because the file now holds a database password, keep it private:

sudo chmod 600 /opt/sphinx/etc/sphinx.conf

Build the index and start searchd

Run the programs from /opt/sphinx as the sphinx user, so that the data directory is created with the right owner. Build all plain indexes first, then start the daemon:

cd /opt/sphinx
sudo -u sphinx ./bin/indexer --config ./etc/sphinx.conf --all
sudo -u sphinx ./bin/searchd --config ./etc/sphinx.conf

The indexer reports how many documents it collected for test1 and says that it skips the non-plain index testrt, which is normal. searchd prints the addresses it listens on and detaches into the background.

Test a search

Connect with the MariaDB client. No Sphinx-specific client is needed:

mariadb -h 127.0.0.1 -P 9306

List the indexes and run a full-text query:

SHOW TABLES;
SELECT * FROM test1 WHERE MATCH('test');
SELECT id, group_id FROM test1 WHERE MATCH('document') AND group_id = 1;

The result contains the document IDs and attributes of the matching rows, ranked by relevance. Your application sends the same queries through its normal MySQL driver, pointed at port 9306, and then loads the full rows from the real database by ID.

Run searchd under systemd

The tarball does not include a systemd unit (only an old example init script in misc/), so you have to write one. The unit below relies on two documented behaviours: searchd detaches into the background on its own, and it shuts down cleanly on SIGTERM, which is the signal systemd sends to stop a service. Stop the manually started daemon first:

cd /opt/sphinx
sudo -u sphinx ./bin/searchd --config ./etc/sphinx.conf --stop

Create /etc/systemd/system/sphinx.service:

[Unit]
Description=Sphinx search daemon
After=network.target mariadb.service

[Service]
Type=forking
User=sphinx
Group=sphinx
WorkingDirectory=/opt/sphinx
ExecStart=/opt/sphinx/bin/searchd --config /opt/sphinx/etc/sphinx.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now sphinx
systemctl status sphinx

If the service does not stay active, read /opt/sphinx/sphinxdata/logs/searchd.log and the output of journalctl -u sphinx.

Keep the index up to date

A plain index is a snapshot: rows added to MariaDB later are not searchable until the index is rebuilt. With --rotate, the indexer builds a new copy and tells the running searchd to switch to it without downtime. Schedule it in the sphinx user's crontab:

sudo crontab -u sphinx -e

Add a line that reindexes every hour:

0 * * * * cd /opt/sphinx && ./bin/indexer --config ./etc/sphinx.conf --rotate --all >/dev/null

If you need new rows to be searchable immediately, use a real-time (RT) index instead. It is created and filled through SphinxQL, with no indexer run:

CREATE TABLE articles (id bigint, title field stored, content field stored, gid uint);
INSERT INTO articles (id, title) VALUES (123, 'hello world');
SELECT * FROM articles WHERE MATCH('hello');

Troubleshooting

  • The indexer cannot load a MySQL client library. indexer loads libmariadb.so or libmysqlclient.so by exactly those names. The runtime package mariadb-connector-c only contains libmariadb.so.3; the unversioned names come from mariadb-connector-c-devel, so make sure that package is installed.
  • Access denied for the sphinx user. Check sql_user and sql_pass, and remember that sql_host = localhost connects through the Unix socket; use 127.0.0.1 if you need sql_port to apply.
  • Remote clients cannot connect. Change the listen address, restart the service and open the port for the client's address only: sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.25" port port="9306" protocol="tcp" accept' followed by sudo firewall-cmd --reload. By default searchd accepts connections without a user name or password; if the port is reachable from other machines, also set up user authentication with the auth_users directive described in the Sphinx manual.

Alternative: Manticore Search

Manticore Search is an open source search engine that began as a fork of Sphinx 2.3 and is actively developed. It speaks the same MySQL-protocol dialect on port 9306 and is the usual choice when you want packages, public source code and features such as replication. Its repository supports RHEL 9 and AlmaLinux 9:

sudo dnf install https://repo.manticoresearch.com/manticore-repo.noarch.rpm
sudo dnf install manticore

Its configuration and index formats have diverged from Sphinx 3, so treat a switch as a migration and follow the Manticore manual. Do not run both on the same ports.

Frequently asked questions

Is Sphinx still maintained?

Yes. Sphinx 3 continues to receive releases from Sphinx Technologies, the most recent being 3.9.1 in December 2025. What ended is the 2.x line and its RPM and DEB packages.

Can I still use the old PHP or Python API clients?

searchd still listens on port 9312 for the native API, but SphinxQL over the MySQL protocol is the primary interface and exposes the full feature set. New code should use a standard MySQL driver against port 9306.

Where does Sphinx keep its data?

In a single data directory, here /opt/sphinx/sphinxdata, set by datadir in the common block or by the --datadir switch. It has fixed subfolders such as indexes, binlogs and logs. Started without any configuration file, searchd uses ./sphinxdata in the current directory. Back the data directory up together with your configuration file, although plain indexes can always be rebuilt from the database.

Does Sphinx replace my database?

No. It holds a search-optimised copy of selected columns. Your application queries Sphinx for matching IDs and attributes, then reads the authoritative rows from MariaDB or MySQL.

Share story:

Continue reading other guides on How VPS.