|
Net::Server - Extensible, general Perl server engine |
Net::Server - Extensible, general Perl server engine
#!/usr/bin/perl -w -T package MyPackage;
use Net::Server; @ISA = qw(Net::Server);
sub process_request {
#...code...
}
MyPackage->run(port => 160); exit;
Visit http://seamons.com/ for the latest version.
* Single Server Mode * Inetd Server Mode * Preforking Simple Mode (PreForkSimple) * Preforking Managed Mode (PreFork) * Forking Mode * Multiplexing Mode using a single process * Multi port accepts on Single, Preforking, and Forking modes * Simultaneous accept/recv on tcp, udp, and unix sockets * Safe signal handling in Fork/PreFork avoids perl signal trouble * User customizable hooks * Chroot ability after bind * Change of user and group after bind * Basic allow/deny access control * Customized logging (choose Syslog, log_file, or STDERR) * HUP able server (clean restarts via sig HUP) * Dequeue ability in all Fork and PreFork modes. * Taint clean * Written in Perl * Protection against buffer overflow * Clean process flow * Extensibility
Net::Server is an extensible, generic Perl server engine.
Net::Server combines the good properties from
Net::Daemon (0.34), NetServer::Generic (1.03), and
Net::FTPServer (1.0), and also from various concepts in
the Apache Webserver.
Net::Server attempts to be a generic server as in
Net::Daemon and NetServer::Generic. It includes with
it the ability to run as an inetd process
(Net::Server::INET), a single connection server
(Net::Server or Net::Server::Single), a forking server
(Net::Server::Fork), a preforking server which maintains
a constant number of preforked children (Net::Server::PreForkSimple),
or as a managed preforking server which maintains the number
of children based on server load (Net::Server::PreFork).
In all but the inetd type, the server provides the ability to
connect to one or to multiple server ports.
Net::Server uses ideologies of Net::FTPServer in order
to provide extensibility. The additional server types are
made possible via ``personalities'' or sub classes of the
Net::Server. By moving the multiple types of servers out of
the main Net::Server class, the Net::Server concept is
easily extended to other types (in the near future, we would
like to add a ``Thread'' personality).
Net::Server borrows several concepts from the Apache
Webserver. Net::Server uses ``hooks'' to allow custom
servers such as SMTP, HTTP, POP3, etc. to be layered over
the base Net::Server class. In addition the
Net::Server::PreFork class borrows concepts of
min_start_servers, max_servers, and min_waiting servers.
Net::Server::PreFork also uses the concept of an flock
serialized accept when accepting on multiple ports (PreFork
can choose between flock, IPC::Semaphore, and pipe to control
serialization).
Net::Server is built around a common class (Net::Server)
and is extended using sub classes, or personalities.
Each personality inherits, overrides, or enhances the base
methods of the base class.
Included with the Net::Server package are several basic personalities, each of which has their own use.
pre_bind, bind, accept, and
post_accept are all overridden as these services are
taken care of by the INET daemon.
server_type parameters may be
given and Net::Server::MultiType will cycle through until it
finds a class that it can use.
process_request
method is never used but the mux_input callback is used
instead (see also the IO::Multiplex manpage). See
examples/samplechat.pl for an example using most of the
features of Net::Server::Multiplex.
max_servers child process. The
server will make sure that at any given time there are always
max_servers available to receive a client request. Each
of these children will process up to max_requests client
connections. This type is good for a heavily hit site that
can dedicate max_server processes no matter what the load.
It should scale well for most applications. Multi port accept
is accomplished using either flock, IPC::Semaphore, or pipe to serialize the
children. Serialization may also be switched on for single
port in order to get around an OS that does not allow multiple
children to accept at the same time. For a further
discussion of serialization see the Net::Server::PreFork manpage.
min_servers child process. The
server will make sure that at any given time there are
at least min_spare_servers but not more than max_spare_servers
available to receive a client request, up
to max_servers. Each of these children will process up
to max_requests client connections. This type is good
for a heavily hit site, and should scale well for most
applications. Multi port accept is accomplished using
either flock, IPC::Semaphore, or pipe to serialize the
children. Serialization may also be switched on for single
port in order to get around an OS that does not allow multiple
children to accept at the same time. For a further
discussion of serialization see the Net::Server::PreFork manpage.
Net::Server was partially written to make it easy to add
new personalities. Using separate modules built upon an
open architecture allows for easy addition of new features,
a separate development process, and reduced code bloat in
the core module.
Once started, the Net::Server will take care of binding to port and waiting for connections. Once a connection is received, the Net::Server will accept on the socket and will store the result (the client connection) in $self->{server}->{client}. This property is a Socket blessed into the the IO::Socket classes. UDP servers are slightly different in that they will perform a recv instead of an accept.
To make programming easier, during the post_accept phase, STDIN and STDOUT are opened to the client connection. This allows for programs to be written using <STDIN> and print ``out\n'' to print to the client connection. UDP will require using a ->send call.
The following is a very simple server. The main
functionality occurs in the process_request method call as
shown below. Notice the use of timeouts to prevent Denial
of Service while reading. (Other examples of using
Net::Server can, or will, be included with this distribution).
#!/usr/bin/perl -w -T #--------------- file test.pl ---------------
package MyPackage;
use strict; use vars qw(@ISA); use Net::Server::PreFork; # any personality will do
@ISA = qw(Net::Server::PreFork);
MyPackage->run(); exit;
### over-ridden subs below
sub process_request {
my $self = shift;
eval {
local $SIG{ALRM} = sub { die "Timed Out!\n" };
my $timeout = 30; # give the user 30 seconds to type a line
my $previous_alarm = alarm($timeout);
while( <STDIN> ){
s/\r?\n$//;
print "You said \"$_\"\r\n";
alarm($timeout);
}
alarm($previous_alarm);
};
if( $@=~/timed out/i ){
print STDOUT "Timed Out.\r\n";
return;
}
}
1;
#--------------- file test.pl ---------------
Playing this file from the command line will invoke a Net::Server using the PreFork personality. When building a server layer over the Net::Server, it is important to use features such as timeouts to prevent Denial of Service attacks.
There are four possible ways to pass arguments to Net::Server. They are passing on command line, using a conf file, passing parameters to run, or using a pre-built object to call the run method.
Arguments consist of key value pairs. On the commandline
these pairs follow the POSIX fashion of --key value or
--key=value, and also key=value. In the conf file the
parameter passing can best be shown by the following regular
expression: ($key,$val)=~/^(\w+)\s+(\S+?)\s+$/. Passing
arguments to the run method is done as follows:
Net::Server-run(key1 => 'val1')>. Passing arguments via
a prebuilt object can best be shown in the following code:
#!/usr/bin/perl -w -T #--------------- file test2.pl --------------- package MyPackage; use strict; use vars (@ISA); use Net::Server; @ISA = qw(Net::Server);
my $server = bless {
key1 => 'val1',
}, 'MyPackage';
$server->run(); #--------------- file test.pl ---------------
All five methods for passing arguments may be used at the
same time. Once an argument has been set, it is not over
written if another method passes the same argument. Net::Server
will look for arguments in the following order:
1) Arguments contained in the prebuilt object. 2) Arguments passed on command line. 3) Arguments passed to the run method. 4) Arguments passed via a conf file. 5) Arguments set in the configure_hook.
Key/value pairs used by the server are removed by the
configuration process so that server layers on top of
Net::Server can pass and read their own parameters.
Currently, Getopt::Long is not used. The following arguments
are available in the default Net::Server or
Net::Server::Single modules. (Other personalities may
use additional parameters and may optionally not use
parameters from the base class.)
Key Value Default conf_file "filename" undef
log_level 0-4 2 log_file (filename|Sys::Syslog) undef
## syslog parameters syslog_logsock (unix|inet) unix syslog_ident "identity" "net_server" syslog_logopt (cons|ndelay|nowait|pid) pid syslog_facility \w+ daemon
port \d+ 20203 host "host" "*" proto (tcp|udp|unix) "tcp" listen \d+ SOMAXCONN
reverse_lookups 1 undef allow /regex/ none deny /regex/ none
## daemonization parameters pid_file "filename" undef chroot "directory" undef user (uid|username) "nobody" group (gid|group) "nobody" background 1 undef setsid 1 undef
no_close_by_child (1|undef) undef
## See Net::Server::Proto::(TCP|UDP|UNIX|etc) ## for more sample parameters.
syslog_logsock, syslog_ident, and
syslog_logopt,and syslog_facility may also be defined.
If a log_file is given or if setsid is set, STDIN and
STDOUT will automatically be opened to /dev/null and STDERR
will be opened to STDOUT. This will prevent any output
from ending up at the terminal.
log_file is equal to ``Sys::Syslog''. May
be either ``unix'' of ``inet''. Default is ``unix''.
See the Sys::Syslog manpage.
log_file is equal to ``Sys::Syslog''. Id
to prepend on syslog entries. Default is ``net_server''.
See the Sys::Syslog manpage.
log_file is equal to ``Sys::Syslog''. May
be either zero or more of ``pid'',``cons'',``ndelay'',``nowait''.
Default is ``pid''. See the Sys::Syslog manpage.
log_file is equal to ``Sys::Syslog''.
See the Sys::Syslog manpage and syslog. Default is ``daemon''.
host:port/proto, host:port, port/proto, or port,
where host represents a hostname residing on the local
box, where port represents either the number of the port
(eg. ``80'') or the service designation (eg. ``http''), and
where proto represents the protocol to be used. See
the Net::Server::Proto manpage. If you are working with unix sockets,
you may also specify socket_file|unix or
socket_file|type|unix where type is SOCK_DGRAM or
SOCK_STREAM. If the protocol is not specified, proto will
default to the proto specified in the arguments. If proto is not
specified there it will default to ``tcp''. If host is not
specified, host will default to host specified in the
arguments. If host is not specified there it will
default to ``*''. Default port is 20203.
See L<IO::Socket>. Not used with udp protocol (or UNIX SOCK_DGRAM).
peerhost
property. Default is to not use reverse_lookups (undef).
user
equal to ``root''.
group
equal to ``root''.
setsid is set.
POSIX::setsid() command to truly daemonize.
Defaults to undef. If a log_file is given or if
setsid is set, STDIN and STDOUT will automatically be
opened to /dev/null and STDERR will be opened to STDOUT.
This will prevent any output from ending up at the terminal.
All of the ARGUMENTS listed above become properties of
the server object under the same name. These properties, as
well as other internal properties, are available during
hooks and other method calls.
The structure of a Net::Server object is shown below:
$self = bless( {
'server' => {
'key1' => 'val1',
# more key/vals
}
}, 'Net::Server' );
This structure was chosen so that all server related properties are grouped under a single key of the object hashref. This is so that other objects could layer on top of the Net::Server object class and still have a fairly clean namespace in the hashref.
You may get and set properties in two ways. The suggested way is to access properties directly via
my $val = $self->{server}->{key1};
Accessing the properties directly will speed the server process. A second way has been provided for object oriented types who believe in methods. The second way consists of the following methods:
my $val = $self->get_property( 'key1' ); my $self->set_property( key1 => 'val1' );
Properties are allowed to be changed at any time with caution (please do not undef the sock property or you will close the client connection).
Net::Server allows for the use of a configuration file to
read in server parameters. The format of this conf file is
simple key value pairs. Comments and white space are
ignored.
#-------------- file test.conf --------------
### user and group to become user somebody group everybody
### logging ? log_file /var/log/server.log log_level 3 pid_file /tmp/server.pid
### optional syslog directive ### used in place of log_file above #log_file Sys::Syslog #syslog_logsock unix #syslog_ident myserver #syslog_logopt pid|cons
### access control allow .+\.(net|com) allow domain\.com deny a.+
### background the process? background 1
### ports to bind (this should bind ### 127.0.0.1:20205 and localhost:20204) ### See Net::Server::Proto host 127.0.0.1 port localhost:20204 port 20205
### reverse lookups ? # reverse_lookups on
#-------------- file test.conf --------------
The process flow is written in an open, easy to override, easy to hook, fashion. The basic flow is shown below.
$self->configure_hook;
$self->configure(@_);
$self->post_configure;
$self->post_configure_hook;
$self->pre_bind;
$self->bind;
$self->post_bind_hook;
$self->post_bind;
$self->pre_loop_hook;
$self->loop;
### routines inside a standard $self->loop # $self->accept; # $self->run_client_connection; # $self->done;
$self->pre_server_close_hook;
$self->server_close;
The server then exits.
During the client processing phase
($self->run_client_connection), the following
represents the program flow:
$self->post_accept;
$self->get_client_info;
$self->post_accept_hook;
if( $self->allow_deny
&& $self->allow_deny_hook ){
$self->process_request;
}else{
$self->request_denied_hook;
}
$self->post_process_request_hook;
$self->post_process_request;
The process then loops and waits for the next connection. For a more in depth discussion, please read the code.
During the server shutdown phase
($self->server_close), the following
represents the program flow:
$self->close_children; # if any
$self->post_child_cleanup_hook;
if( Restarting server ){
$self->restart_close_hook();
$self->hup_server;
}
exit;
Net::Server provides a number of ``hooks'' allowing for
servers layered on top of Net::Server to respond at
different levels of execution.
$self->configure_hook()->run()
method is called. This hook allows for setting up the
object before any built in configuration takes place.
This allows for custom configurability.
$self->post_configure_hook()->pre_bind() and
->bind() methods are called. This hook allows for
verifying configuration parameters.
$self->post_bind_hook()$self->pre_loop_hook()$self->post_accept_hook()$self->allow_deny_hook()$self->allow_deny() routine. If this hook
returns 1, the client request will be processed,
otherwise, the request will be denied processing.
$self->request_denied_hook()$self->allow_deny() or
$self->allow_deny_hook() have taken place.
$self->post_process_request_hook()$self->pre_server_close_hook()$self->write_to_log_hooklog_file. The arguments passed are a
log level of 0 to 4 (4 being very verbose), and a log line.
If log_file is equal to ``Sys::Syslog'', then logging will
go to Sys::Syslog and will bypass the write_to_log_hook.
$self->fatal_hook$self->post_child_cleanup_hook$self->restart_open_hook$self->restart_close_hook
Each of the server personalities (except for INET), support
restarting via a HUP signal (see ``kill -l''). When a HUP
is received, the server will close children (if any), make
sure that sockets are left open, and re-exec using
the same commandline parameters that initially started the
server. (Note: for this reason it is important that @ARGV
is not modified until ->run is called.
There are several tasks to perform before the alpha label can be removed from this software:
The following files are installed as part of this distribution.
Net/Server.pm Net/Server/Fork.pm Net/Server/INET.pm Net/Server/MultiType.pm Net/Server/PreForkSimple.pm Net/Server/PreFork.pm Net/Server/Single.pm Net/Server/Daemonize.pm Net/Server/SIG.pm Net/Server/Proto.pm Net/Server/Proto/*.pm
Download and extract tarball before running these commands in its base directory:
perl Makefile.PL make make test make install
For RPM installation, download tarball before running these commands in your _topdir:
rpm -ta SOURCES/Net-Server-*.tar.gz rpm -ih RPMS/noarch/perl-Net-Server-*.rpm
Paul T. Seamons <paul at seamons.com>
Thanks to Rob Brown (bbb at cpan.org) for help with miscellaneous concepts such as tracking down the serialized select via flock ala Apache and the reference to IO::Select making multiport servers possible. And for researching into allowing sockets to remain open upon exec (making HUP possible). Rob Brown is also the maintainer for Net::Server.
Thanks to Jonathan J. Miner <miner at doit.wisc.edu> for patching a blatant problem in the reverse lookups.
Thanks to Bennett Todd <bet at rahul.net> for pointing out a problem in Solaris 2.5.1 which does not allow multiple children to accept on the same port at the same time. Also for showing some sample code from Viktor Duchovni which now represents the semaphore option of the serialize argument in the PreFork server.
Thanks to traveler and merlyn from http://perlmonks.org for pointing me in the right direction for determining the protocol used on a socket connection.
Thanks to Jeremy Howard <j+daemonize at howard.fm> for numerous suggestions and for work on Net::Server::Daemonize.
Thanks to Vadim <vadim at hardison.net> for patches to implement parent/child communication on PreFork.pm.
Please see also the Net::Server::Fork manpage, the Net::Server::INET manpage, the Net::Server::PreForkSimple manpage, the Net::Server::PreFork manpage, the Net::Server::MultiType manpage, the Net::Server::Single manpage
Copyright (C) 2001, Paul T Seamons
paul at seamons.com
http://seamons.com/
This package may be distributed under the terms of either the
GNU General Public License
or the
Perl Artistic License
All rights reserved.
|
Net::Server - Extensible, general Perl server engine |