NAME
   Net::Server - Extensible, general Perl server engine

SYNOPSIS
     #!/usr/bin/perl -w -T
     package MyPackage;

     use Net::Server;
     @ISA = qw(Net::Server);

     sub process_request {
        #...code...
     }

     MyPackage->run(port => 160);
     exit;

OBTAINING
   Visit http://seamons.com/ for the latest version.

FEATURES
    * 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

DESCRIPTION
   "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).

PERSONALITIES
   "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.

   Fork
       Found in the module Net/Server/Fork.pm (see the Net::Server::Fork
       manpage). This server binds to one or more ports and then waits for
       a connection. When a client request is received, the parent forks a
       child, which then handles the client and exits. This is good for
       moderately hit services.

   INET
       Found in the module Net/Server/INET.pm (see the Net::Server::INET
       manpage). This server is designed to be used with inetd. The
       "pre_bind", "bind", "accept", and "post_accept" are all overridden
       as these services are taken care of by the INET daemon.

   MultiType
       Found in the module Net/Server/MultiType.pm (see the
       Net::Server::MultiType manpage). This server has no server
       functionality of its own. It is designed for servers which need a
       simple way to easily switch between different personalities.
       Multiple "server_type" parameters may be given and
       Net::Server::MultiType will cycle through until it finds a class
       that it can use.

   Multiplex
       Found in the module Net/Server/Multiplex.pm (see the
       Net::Server::Multiplex manpage). This server binds to one or more
       ports. It uses IO::Multiplex to multiplex between waiting for new
       connections and waiting for input on currently established
       connections. This personality is designed to run as one process
       without forking. The "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.

   PreForkSimple
       Found in the module Net/Server/PreFork.pm (see the
       Net::Server::PreFork manpage). This server binds to one or more
       ports and then forks "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.

   PreFork
       Found in the module Net/Server/PreFork.pm (see the
       Net::Server::PreFork manpage). This server binds to one or more
       ports and then forks "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.

   Single
       All methods fall back to Net::Server. This personality is provided
       only as parallelism for Net::Server::MultiType.

   "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.

SOCKET ACCESS
   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.

SAMPLE CODE
   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.

ARGUMENTS
   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.

   conf_file
       Filename from which to read additional key value pair arguments for
       starting the server. Default is undef.

   log_level
       Ranges from 0 to 4 in level. Specifies what level of error will be
       logged. "O" means logging is off. "4" means very verbose. These
       levels should be able to correlate to syslog levels. Default is 2.
       These levels correlate to syslog levels as defined by the following
       key/value pairs: 0=>'err', 1=>'warning', 2=>'notice', 3=>'info',
       4=>'debug'.

   log_file
       Name of log file to be written to. If no name is given and hook is
       not overridden, log goes to STDERR. Default is undef. If the magic
       name "Sys::Syslog" is used, all logging will take place via the
       Sys::Syslog module. If syslog is used the 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.

   pid_file
       Filename to store pid of parent process. Generally applies only to
       forking servers. Default is none (undef).

   syslog_logsock
       Only available if "log_file" is equal to "Sys::Syslog". May be
       either "unix" of "inet". Default is "unix". See the Sys::Syslog
       manpage.

   syslog_ident
       Only available if "log_file" is equal to "Sys::Syslog". Id to
       prepend on syslog entries. Default is "net_server". See the
       Sys::Syslog manpage.

   syslog_logopt
       Only available if "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.

   syslog_facility
       Only available if "log_file" is equal to "Sys::Syslog". See the
       Sys::Syslog manpage and the syslog manpage. Default is "daemon".

   port
       See the Net::Server::Proto manpage. Local port/socket on which to
       bind. If low port, process must start as root. If multiple ports are
       given, all will be bound at server startup. May be of the form
       "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.

   host
       Local host or addr upon which to bind port. If a value of '*' is
       given, the server will bind that port on all available addresses on
       the box. See the Net::Server::Proto manpage. See the IO::Socket
       manpage.

   proto
       See the Net::Server::Proto manpage. Protocol to use when binding
       ports. See the IO::Socket manpage. As of release 0.70, Net::Server
       supports tcp, udp, and unix. Other types will need to be added later
       (or custom modules extending the Net::Server::Proto class may be
       used).

   listen
         See L<IO::Socket>.  Not used with udp protocol (or UNIX SOCK_DGRAM).

   reverse_lookups
       Specify whether to lookup the hostname of the connected IP.
       Information is cached in server object under "peerhost" property.
       Default is to not use reverse_lookups (undef).

   allow/deny
       May be specified multiple times. Contains regex to compare to
       incoming peeraddr or peerhost (if reverse_lookups has been enabled).
       If allow or deny options are given, the incoming client must match
       an allow and not match a deny or the client connection will be
       closed. Defaults to empty array refs.

   chroot
       Directory to chroot to after bind process has taken place and the
       server is still running as root. Defaults to undef.

   user
       Userid or username to become after the bind process has occured.
       Defaults to "nobody." If you would like the server to run as root,
       you will have to specify "user" equal to "root".

   group
       Groupid or groupname to become after the bind process has occured.
       Defaults to "nobody." If you would like the server to run as root,
       you will have to specify "group" equal to "root".

   background
       Specifies whether or not the server should fork after the bind
       method to release itself from the command line. Defaults to undef.
       Process will also background if "setsid" is set.

   setsid
       Specifies whether or not the server should fork after the bind
       method to release itself from the command line and then run the
       "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.

   no_close_by_child
       Specifies whether or not a forked child process has permission or
       not to shutdown the entire server process. If set to 1, the child
       may NOT signal the parent to shutdown all children. Default is undef
       (not set).

PROPERTIES
   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).

CONFIGURATION FILE
   "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 --------------

PROCESS FLOW
   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;

HOOKS
   "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()"
       This hook takes place immediately after the "->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()"
       This hook occurs just after the reading of configuration parameters
       and initiation of logging and pid_file creation. It also occurs
       before the "->pre_bind()" and "->bind()" methods are called. This
       hook allows for verifying configuration parameters.

   "$self->post_bind_hook()"
       This hook occurs just after the bind process and just before any
       chrooting, change of user, or change of group occurs. At this point
       the process will still be running as the user who started the
       server.

   "$self->pre_loop_hook()"
       This hook occurs after chroot, change of user, and change of group
       has occured. It allows for preparation before looping begins.

   "$self->post_accept_hook()"
       This hook occurs after a client has connected to the server. At this
       point STDIN and STDOUT are mapped to the client socket. This hook
       occurs before the processing of the request.

   "$self->allow_deny_hook()"
       This hook allows for the checking of ip and host information beyond
       the "$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()"
       This hook occurs if either the "$self->allow_deny()" or
       "$self->allow_deny_hook()" have taken place.

   "$self->post_process_request_hook()"
       This hook occurs after the processing of the request, but before the
       client connection has been closed.

   "$self->pre_server_close_hook()"
       This hook occurs before the server begins shutting down.

   "$self->write_to_log_hook"
       This hook handles writing to log files. The default hook is to write
       to STDERR, or to the filename contained in the parameter "log_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"
       This hook occurs when the server has encountered an unrecoverable
       error. Arguments passed are the error message, the package, file,
       and line number. The hook may close the server, but it is suggested
       that it simply return and use the built in shut down features.

   "$self->post_child_cleanup_hook"
       This hook occurs in the parent server process after all children
       have been shut down and just before the server either restarts or
       exits. It is intended for additional cleanup of information. At this
       point pid_files and lockfiles still exist.

   "$self->restart_open_hook"
       This hook occurs if a server has been HUPed (restarted via the HUP
       signal. It occurs just before reopening to the filenos of the
       sockets that were already opened.

   "$self->restart_close_hook"
       This hook occurs if a server has been HUPed (restarted via the HUP
       signal. It occurs just before restarting the server via exec.

RESTARTING
   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.

TO DO
   There are several tasks to perform before the alpha label can be removed
   from this software:

   Use It
       The best way to further the status of this project is to use it.
       There are immediate plans to use this as a base class in
       implementing some mail servers and banner servers on a high hit
       site.

   Other Personalities
       Explore any other personalities

   Net::Server::HTTP, etc
       Create various types of servers. Possibly, port exising servers to
       user Net::Server as a base layer.

FILES
     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

INSTALL
   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

AUTHOR
   Paul T. Seamons <paul at seamons.com>

THANKS
   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.

SEE ALSO
   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
     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.