NAME

Sphinx::Manager - Sphinx search engine management (start/stop)

SYNOPSIS

    use Sphinx::Manager;

    my $mgr = Sphinx::Manager->new({ config_file => '/etc/sphinx.conf' });
    $mgr->start_searchd;
    $mgr->restart_searchd;
    $mgr->reload_searchd;
    $mgr->stop_searchd;
    $mgr->get_searchd_pid;
    $mgr->run_indexer;

DESCRIPTION

This module provides utilities to start, stop, restart, and reload the Sphinx search engine binary (searchd), and to run the Sphinx indexer program. The utilities are designed to handle abnormal conditions, such as PID files not being present when expected, and so should be robust in most situations.

CONSTRUCTOR

new

    $mgr = Sphinx::Manager->new(\%opts);

Create a new Sphinx manager. The names of options are the same as the setter/getter functions listed below.

SETTERS/GETTERS

config_file

    $mgr->config_file($filename)
    $filename = $mgr->config_file;

Set/get the configuration file. Defaults to sphinx.conf in current working directory.

pid_file

    $mgr->pid_file($filename)
    $filename = $mgr->pid_file;

Set/get the PID file. If given, this will be used in preference to any value in the given config_file.

bindir

    $mgr->bindir($dir)
    $dir = $mgr->bindir;

Set/get the directory in which to find the Sphinx binaries.

debug

    $mgr->debug(1);
    $mgr->debug(0);
    $debug_state = $mgr->debug;

Enable/disable debugging messages, or read back debug status.

process_timeout

    $mgr->process_timeout($secs)
    $secs = $mgr->process_timeout;

Set/get the time (in seconds) to wait for processes to start or stop.

searchd_bin

Optional full path to searchd. If not specified, normal rules for finding an executable in the PATH environment are used.

searchd_args

    $mgr->searchd_args(\@args)
    $args = $mgr->searchd_args;

Set/get the extra command line arguments to pass to searchd when started using start_searchd. These should be in the form of an array, each entry comprising one option or option argument. Arguments should exclude '--config CONFIG_FILE', which is included on the command line by default.

searchd_sudo

Optional sudo wrapper for running searchd as root or another user. Set to 'sudo', or 'sudo -u USER', or sudo with any other options. If not set, searchd is run as the current user. Of course, for this to work, sudo privileges should be enabled for the current user and typically without a password. Could also be set to the name of any other wrapper program to provide custom functionality.

indexer_args

    $mgr->indexer_args(\@args)
    $args = $mgr->indexer_args;

Set/get the extra command line arguments to pass to the indexer program when started using run_indexer. These should be in the form of an array, each entry comprising one option or option argument. Arguments should exclude '--config CONFIG_FILE', which is included on the command line by default.

indexer_sudo

Same as searchd_sudo above, for running the indexer.

max_fd

Maximum file descriptor number to close prior to launching searchd. This is to support environments such as mod_perl where open file descriptors would otherwise be inherited and left open in the subprocess. Detecting open files is problematic so instead we close all files from 0 to max_fd.

pre_exec_callback

A callback function that provides an alternative to max_fd, allowing the provider of the callback function to clean up resources (like closing files) after the process forks and before it execs searchd. If pre_exec_callback is provided, max_fd is not used.

The callback is invoked as

  pre_exec_callback($mgr, \@searchd_exec_args)

This also provides the opportunity to modify @searchd_exec_args if the caller wishes.

METHODS

start_searchd

    $mgr->start_searchd;
    $mgr->start_searchd($ok_if_running);

Starts the Sphinx searchd daemon. Unless $ok_if_running is set, dies if searchd cannot be started or if it is already running. If $ok_if_running is set and searchd is found to be already running, returns quietly without trying to start it.

stop_searchd

    $mgr->stop_searchd;

Stops Sphinx searchd daemon. Dies if searchd cannot be stopped.

restart_searchd

    $mgr->restart_searchd;

Stops and then starts the searchd daemon.

reload_searchd

    $mgr->reload_searchd;

Sends a HUP signal to the searchd daemon if it is running, to tell it to reload its databases; otherwise starts searchd.

get_searchd_pid

    $pids = $mgr->get_searchd_pid;

Returns an array ref containing the PID(s) of the searchd daemon. If the PID file is in place and searchd is running, then an array containing a single PID is returned. If the PID file is not present or is empty, the process table is checked for other searchd processes running with the specified config file; if found, all are returned in the array.

run_indexer(@args)

Runs the indexer program; dies on error. Arguments passed to the indexer are "--config CONFIG_FILE" followed by args set through indexer_args, followed by any additional args given as parameters to run_indexer.

CAVEATS

This module has been tested primarily on Linux. It should work on any other operating systems where fork() is supported and Proc::ProcessTable works.

AUTHOR

Jon Schutz, <http://notes.jschutz.net>

BUGS

Please report any bugs or feature requests to "bug-sphinx-config at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sphinx-Manager>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Sphinx::Manager

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Sphinx-Manager>
CPAN Ratings
<http://cpanratings.perl.org/d/Sphinx-Manager>
RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sphinx-Manager>
Search CPAN
<http://search.cpan.org/dist/Sphinx-Manager>

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.