Server::Control -- Flexible apachectl style control for servers
version 0.20
use Server::Control::Apache; my $apache = Server::Control::Apache->new( conf_file => '/my/apache/dir/conf/httpd.conf' ); if ( !$apache->is_running() ) { $apache->start(); }
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.
Server::Control
The original motivation was to eliminate all those little annoyances that can occur when starting and stopping a server doesn't quite go right.
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
Reports what is listening to a port when it is busy (with Unix::Lsof)
The following subclasses are currently available as part of this distribution:
Server::Control::Apache - For Apache httpd
Server::Control::Nginx - For Nginx
Server::Control::Starman - For Starman
Server::Control::HTTPServerSimple - For HTTP::Server::Simple
Server::Control::NetServer - For Net::Server
There may be other subclasses available on CPAN.
You can pass the following common parameters to the constructor, or include them in an rc file.
Some subclasses can deduce some of these parameters without needing an explicit value passed in. For example, Server::Control::Apache can deduce many of these from the Apache conf file.
The absolute path to the server binary, e.g. /usr/sbin/httpd or /usr/local/bin/nginx. By default, searches for the appropriate command in the user's PATH and uses the first one found, or throws an error if one cannot be found.
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".
localhost
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.
Location of logs. Defaults to server_root/logs if server_root is defined, otherwise undef.
Name of the server to be used in output and logs. A generic default will be chosen if none is provided, based on either "server_root" or the classname.
Path to pid file. Will throw an error if this cannot be determined.
Number of seconds (can be fractional) between status checks when waiting for server start or stop. Defaults to 0.2.
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".
Method to use for the "restart" action - one of "hup" or "stopstart", defaults to "stopstart".
Root directory of server, for conf files, log files, etc. This will affect defaults of other parameters like log_dir. You must create this directory, it will not be created for you.
Path to an rc file containing, in YAML form, one or parameters to pass to the constructor. If not specified, will look for "server_root"/serverctl.yml. e.g.
# This is my serverctl.yml use_sudo: 1 wait_for_status-secs: 5
Parameters passed explicitly to the constructor take precedence over parameters in an rc file.
Whether to use 'sudo' when attempting to start and stop server. Defaults to true if port < 1024, false otherwise.
A URL to visit after the server has been started or HUP'd, in order to validate the state of the server. The URL just needs to return an OK result to be considered valid, unless "validate_regex" is also specified.
A regex to match against the content returned by "validate_url". The content must match the regex for the server to be considered valid.
Number of seconds to wait for server start or stop before reporting error. Defaults to 10.
Start the server. Calls "do_start" internally. Returns 1 if the server started successfully, 0 if not (e.g. it was already running, or there was an error starting it).
Stop the server. Calls "do_stop" internally. Returns 1 if the server stopped successfully, 0 if not (e.g. it was already stopped, or there was an error stopping it).
If the server is not running, start it. Otherwise, restart the server using the "restart_method" - one of "hup" or "stopstart", defaults to "stopstart".
Sends the server parent process a HUP signal, which is a standard way of restarting it. Returns 1 if the server was successfully signalled and is still running afterwards, 0 if not.
Note: HUP is not yet fully supported for NetServer and HTTPServerSimple, because it depends on a valid command-line that can be re-exec'd.
Stops the server (if it is running), then starting it. Returns 1 if the server restarted succesfully, 0 if not.
Send a TERM signal to the child processes of the server's main process. This will force forking servers, such as Apache and Net::Server::Prefork, to fork new children. This can serve as a cheap restart in a development environment, if the resources you want to refresh are being loaded in the child rather than the parent.
TERM
Apache
Net::Server::Prefork
Returns the list of child pids that were sent a TERM.
Log the server's status.
Helper method to implement a CLI (command-line interface) like apachectl. This is used by two scripts that come with this distribution, apachectlp and serverctlp. In general the usage looks like this:
#!/usr/bin/perl -w use strict; use Server::Control::Foo; Server::Control::Foo->handle_cli();
handle_cli will process the following options from @ARGV:
handle_cli
@ARGV
-v|--verbose - set log level to debug
debug
-q|--quiet - set log level to warning respectively
warning
-c|--class - forwards the call to the specified classname. The classname is prefixed with "Server::Control::" unless it begins with a "+".
-h|--help - prints a help message using Pod::Usage
-k|--action - calls this on the Server::Control::MyServer object (required)
Server::Control::MyServer
Any constructor parameter accepted by Server::Control or the specific subclass, with underscores replaced by dashes - e.g. --bind-addr, --wait-for-status-secs
Any parameters passed to handle_cli will be passed to the Server::Control constructor, but may be overriden by @ARGV options.
In general, any customization to the default command-line handling is best done in your Server::Control subclass rather than the script itself. For example, see Server::Control::Apache and its overriding of _cli_option_pairs.
_cli_option_pairs
Log output is automatically diverted to STDOUT, as would be expected for a CLI.
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.
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.
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::RUNNING
Server::Control::LISTENING - Something is listening to the specified bind address and port
Server::Control::LISTENING
Server::Control::ACTIVE - Equal to RUNNING & LISTENING
Server::Control::ACTIVE
Server::Control::INACTIVE - Equal to 0 (neither RUNNING nor LISTENING)
Server::Control::INACTIVE
Returns status as a human-readable string, e.g. "server 'foo' is not running"
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_cli", which will tell Log::Any to send logs to STDOUT.
Log::Any
Server::Control uses Moose, so ideally subclasses will as well. See Server::Control::Apache for an example.
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_system_command".
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".
Runs the specified $cmd on the command line. Adds sudo if necessary (see "use_sudo"), logs the command, and throws runtime errors appropriately.
This method is called after the server starts or is HUP'd. It gives the subclass a chance to validate the server in a particular way. It should return a boolean indicating whether the server is in a valid state.
The default validate_server uses "validate_url" and "validate_regex" to make a test web request against the server. If these are not provided then it simply returns true.
validate_server
Because Server::Control uses Moose, it is easy to define plugins that modify its methods. If a plugin is meant for public consumption, we recommend that it be implemented as a role and named Server::Control::Plugin::*.
Moose
Server::Control::Plugin::*
In addition to the methods documented above, the following empty hook methods are called for plugin convenience:
successful_start - called when a start() succeeds
successful_stop - called when a stop() succeeds
Server::Control uses the MooseX::Traits role if it is installed, so you can call it with new_with_traits(). The default trait_namespace is Server::Control::Plugin.
new_with_traits()
Server::Control::Plugin
For example, here is a role that sends an email whenever a server is successfully started or stopped:
package Server::Control::Plugin::EmailOnStatusChange; use Moose::Role; has 'email_status_to' => ( is => 'ro', isa => 'Str', required => 1 ); after 'successful_start' => sub { shift->send_email("server started"); }; after 'successful_stop' => sub { shift->send_email("server stopped"); }; __PACKAGE__->meta->make_immutable(); sub send_email { my ( $self, $subject ) = @_; ...; } 1;
and here's how you'd use it:
my $apache = Server::Control::Apache->new_with_traits( traits => ['EmailOnStatusChange'], email_status_to => 'joe@domain.org', conf_file => '/my/apache/dir/conf/httpd.conf' );
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
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.
serverctlp, Server::Control::Apache
This software is copyright (c) 2011 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Server::Control, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Server::Control
CPAN shell
perl -MCPAN -e shell install Server::Control
For more information on module installation, please visit the detailed CPAN module installation guide.