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

AUTHOR
    Paul T. Seamons paul@seamons.com

THANKS
    Thanks to Rob Brown <rbrown@about-inc.com> 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).

    Thanks to Jonathan J. Miner <miner@doit.wisc.edu> for patching a blatant
    problem in the reverse lookups.

    Thanks to Bennett Todd <bet@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@howard.fm> for numerous suggestions
    and for work on Net::Server::Daemonize.

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

