NAME Server::Control -- Flexible apachectl style control for servers SYNOPSIS use Server::Control::Apache; my $apache = Server::Control::Apache->new( root_dir => '/my/apache/dir', port => 80 ); 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. FEATURES * Checks server status in multiple ways (looking for an active process, contacting the server's port) * Tails the error log when server fails to start * Detects and handles corrupt or out-of-date pid files * Uses sudo by default when using restricted (< 1024) port AVAILABLE SUBCLASSES `Server::Control' is designed to be subclassed for different types of servers. 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: 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. port At least one port that server will listen to, so that `Server::Control' can check it on start/stop. Required. 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_start_secs Number of seconds to wait for server start before reporting error. Defaults to 10. wait_for_stop_secs Number of seconds to wait for server 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 ($cmd, $verbose) Helper method to process a command-line command for a script like apachectl. If *$cmd* is one of start, stop, restart, or ping, it will be called on the object; otherwise, an appropriate usage error will be thrown. This method will also cause messages to be logged to STDOUT, as is expected for a command-line script. *$verbose* is a boolean indicating whether the log level will be set to 'debug' or 'info'. 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, so you have control over where logs will be 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 * When a port is being listened to unexpectedly, attempt to report which process is listening (via lsof, fuser, etc.) * Possibly add pre- and post- start and stop augment hooks like MooseX::Control 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.