NAME
    Server::Control -- Flexible apachectl style control for servers

SYNOPSIS
        use Server::Control::Apache;

        my $apache = Server::Control::Apache->new(
            conf_file => '/my/apache/dir/conf/httpd.conf'
        );
        if ( !$apache->is_running() ) {
            $apache->start();
        }

DESCRIPTION
    `Server::Control' allows you to control servers in the spirit of
    apachectl, where a server is any background process which listens to a
    port and has a pid file. It is designed to be subclassed for different
    types of servers.

FEATURES
    *   Checks server status in multiple ways (looking for an active
        process, contacting the server's port)

    *   Detects and handles corrupt or out-of-date pid files

    *   Tails the error log when server fails to start

    *   Uses sudo by default when using restricted (< 1024) port

    *   With Unix::Lsof installed, reports what is listening to a port when
        it is busy

AVAILABLE SUBCLASSES
    The following subclasses are currently available as part of this
    distribution:

    *   Server::Control::Apache - Apache httpd

    *   Server::Control::Apache - HTTP::Server::Simple server

    *   Server::Control::Apache - Net::Server server

    These will probably be moved into their own distributions once the
    implementation stabilizes.

CONSTRUCTOR
    You can pass the following common options to the constructor. Some
    subclasses can deduce some of these options without needing an explicit
    value passed in. For example, Server::Control::Apache can deduce many of
    these from the Apache conf file.

    bind_addr
        At least one address that the server binds to, so that
        `Server::Control' can check it on start/stop. Defaults to
        `localhost'. See also port.

    description
        Description of the server to be used in output and logs. A generic
        default will be chosen if none is provided.

    error_log
        Location of error log. Defaults to *log_dir*/error_log if *log_dir*
        is defined, otherwise undef. When a server fails to start,
        Server::Control attempts to show recent messages in the error log.

    log_dir
        Location of logs. Defaults to *root_dir*/logs if *root_dir* is
        defined, otherwise undef.

    pid_file
        Path to pid file. Will throw an error if this cannot be determined.

    poll_for_status_secs
        Number of seconds (can be fractional) between status checks when
        waiting for server start or stop. Defaults to 0.2.

    port
        At least one port that server will listen to, so that
        `Server::Control' can check it on start/stop. Will throw an error if
        this cannot be determined. See also bind_addr.

    root_dir
        Root directory of server, for conf files, log files, etc. This will
        affect defaults of other options like *log_dir*.

    use_sudo
        Whether to use 'sudo' when attempting to start and stop server.
        Defaults to true if *port* < 1024, false otherwise.

    wait_for_status_secs
        Number of seconds to wait for server start or stop before reporting
        error. Defaults to 10.

METHODS
  Action methods

    start
        Start the server. Calls do_start internally.

    stop
        Stop the server. Calls do_stop internally.

    restart
        Restart the server (by stopping it, then starting it).

    ping
        Log the server's status.

    handle_cmdline (params)
        Helper method to process a command-line command for a script like
        apachectl. Takes the following key/value parameters:

        *   *cmd* - one of start, stop, restart, or ping. It will be called
            on the Server::Control object. An appropriate usage error will
            be thrown for a bad command. If *cmd* is not specified, it will
            be taken from $ARGV[0].

        *   *$verbose* - a boolean indicating whether the log level will be
            set to 'debug' or 'info'. Would typically come from a -v or
            --verbose switch. Default false.

  Status methods

    is_running
        If the server appears running (the pid file exists and contains a
        valid process), returns a Proc::ProcessTable::Process object
        representing the process. Otherwise returns undef.

    is_listening
        Returns a boolean indicating whether the server is listening to the
        address and port specified in *bind_addr* and *port*. This is
        checked to determine whether a server start or stop has been
        successful.

    status
        Returns status of server as an integer. Use the following constants
        to interpret status:

        *   `Server::Control::RUNNING' - Pid file exists and contains a
            valid process

        *   `Server::Control::LISTENING' - Something is listening to the
            specified bind address and port

        *   `Server::Control::ACTIVE' - Equal to RUNNING & LISTENING

        *   `Server::Control::INACTIVE' - Equal to 0 (neither RUNNING nor
            LISTENING)

    status_as_string
        Returns status as a human-readable string, e.g. "server 'foo' is not
        running"

LOGGING
    `Server::Control' uses Log::Any for logging events. See Log::Any
    documentation for how to control where logs get sent, if anywhere.

    The exception is handle_cmdline, which will tell `Log::Any' to send logs
    to STDOUT.

IMPLEMENTING SUBCLASSES
    `Server::Control' uses Moose, so ideally subclasses will as well. See
    Server::Control::Apache for an example.

  Subclass methods

    do_start
        This actually starts the server - it is called by start and must be
        defined by the subclass. Any parameters to start are passed here. If
        your server is started via the command-line, you may want to use
        run_command.

    do_stop ($proc)
        This actually stops the server - it is called by stop and may be
        defined by the subclass. By default, it will send a SIGTERM to the
        process. *$proc* is a Proc::ProcessTable::Process object
        representing the current process, as returned by is_running.

    run_command ($cmd)
        Runs the specified *$cmd* on the command line. Adds sudo if
        necessary (see use_sudo), logs the command, and throws runtime
        errors appropriately.

RELATED MODULES
    *   App::Control - Same basic idea for any application with a pid file.
        No features specific to a server listening on a port, and not easily
        subclassable, as all commands are handled in a single case
        statement.

    *   MooseX::Control - A Moose role for controlling applications with a
        pid file. Nice extendability. No features specific to a server
        listening on a port, and assumes server starts via a command-line
        (unlike pure-Perl servers, say). May end up using this role.

    *   Nginx::Control, Sphinx::Control, Lighttpd::Control - Modules which
        use MooseX::Control

TO DO
    *   Write a plugin to dynamically generate conf files

ACKNOWLEDGMENTS
    This module was developed for the Digital Media group of the Hearst
    Corporation, a diversified media company based in New York City. Many
    thanks to Hearst management for agreeing to this open source release.

AUTHOR
    Jonathan Swartz

COPYRIGHT & LICENSE
    Copyright (C) 2007 Jonathan Swartz, all rights reserved.

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

