SERVER(1)             User Contributed Perl Documentation            SERVER(1)



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

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

           use base qw(Net::Server);

           sub process_request {
               my $self = shift;
               while (<STDIN>) {
                   s/\r?\n$//;
                   print "You said ’$_’\r\n"; # basic echo
                   last if /quit/i;
               }
           }

           MyPackage->run(port => 160);

DDIISSCCLLAAIIMMEERR
       This version of Net::Server (0.99.6.1) has been submitted by the munin
       maintainers (munin-monitoring.org) in order to enable ipv6 support in
       munin.  The version number (over 0.99) was chosen to imply IPv6 support
       and that it was the first such version.

       The patches we used were found in Debians perl repository at
       http://packages.qa.debian.org/libn/libnet-server-perl.html and we’ve
       made no atempts to improve upon these.  We tested by patching
       Net::Server and then connecting to munin node with "telnet ::1 4949"
       which worked quite nicely thanks very much.  Many thanks to the Debian
       community for developing the patches.

       I/we are sorry, but cannot we be counted on to do any further develop-
       ment or support of Net::Server.  Whatever time we may or may not have
       will go into munin.

FFEEAATTUURREESS
        * IPv6 support
        * 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
        * Basic HTTP Daemon handler
        * Simultaneous accept/recv on tcp, udp, and unix and ssl/tcp sockets
        * Working SSL 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

DDEESSCCRRIIPPTTIIOONN
       "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 "per-
       sonalities" or sub classes of the "Net::Server".  By moving the multi-
       ple 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 addi-
       tion 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).

PPEERRSSOONNAALLIITTIIEESS
       "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 Net::Server::Fork).
           This server binds to one or more ports and then waits for a connec-
           tion.  When a client request is received, the parent forks a child,
           which then handles the client and exits.  This is good for moder-
           ately hit services.

       INET
           Found in the module Net/Server/INET.pm (see Net::Server::INET).
           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 Net::Server::Mul-
           tiType).  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 Net::Server::Mul-
           tiplex).  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 per-
           sonality 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 IO::Multiplex).  See examples/sam-
           plechat.pl for an example using most of the features of
           Net::Server::Multiplex.

       PreForkSimple
           Found in the module Net/Server/PreFork.pm (see Net::Server::Pre-
           Fork).  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 dis-
           cussion of serialization see Net::Server::PreFork.

       PreFork
           Found in the module Net/Server/PreFork.pm (see Net::Server::Pre-
           Fork).  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 dis-
           cussion of serialization see Net::Server::PreFork.

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

       HTTP
           Not a distinct personality.  Provides a basic HTTP daemon.  This
           can be combined with the SSLEAY proto to provide an HTTPS Daemon.
           See Net::Server::HTTP.

       "Net::Server" was partially written to make it easy to add new person-
       alities.  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.

SSOOCCKKEETT AACCCCEESSSS
       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 rreeccvv instead of an
       aacccceepptt.

       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.

SSAAMMPPLLEE CCOODDEE
       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 distribu-
       tion).

           #!/usr/bin/perl -w -T

           package MyPackage;

           use strict;
           use base qw(Net::Server::PreFork); # any personality will do

           MyPackage->run;

           ### 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 some lines

                   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;

       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 pre-
       vent Denial Of Service attacks.

AARRGGUUMMEENNTTSS
       There are five possible ways to pass arguments to Net::Server.  They
       are _p_a_s_s_i_n_g _t_o _t_h_e _n_e_w _m_e_t_h_o_d, _p_a_s_s_i_n_g _o_n _c_o_m_m_a_n_d _l_i_n_e, _p_a_s_s_i_n_g _p_a_r_a_m_e_-
       _t_e_r_s _t_o _r_u_n, _u_s_i_n_g _a _c_o_n_f _f_i_l_e, _r_e_t_u_r_n_i_n_g _v_a_l_u_e_s _i_n _t_h_e _d_e_f_a_u_l_t___v_a_l_u_e_s
       _m_e_t_h_o_d, or _c_o_n_f_i_g_u_r_i_n_g _t_h_e _v_a_l_u_e_s _i_n _p_o_s_t___c_o_n_f_i_g_u_r_e___h_o_o_k.

       The "options" method is used to determine which arguments the server
       will search for and can be used to extend the parsed parameters.  Any
       arguments found from the command line, parameters passed to run, and
       arguments found in the conf_file will be matched against the keys of
       the options template.  Any commandline parameters that do not match
       will be left in place and can be further processed by the server in the
       various hooks (by looking at @ARGV).  Arguments passed to new will
       automatically win over any other options (this can be used if you would
       like to disallow a user passing in other arguments).

       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’)>>.  Pass-
       ing arguments via a prebuilt object can best be shown in the following
       code:

           #!/usr/bin/perl -w -T

           package MyPackage;
           use strict;
           use base qw(Net::Server);

           my $server = MyPackage->new({
               key1 => ’val1’,
           });

           $server->run;

       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 passed to the C<new> method.
         2) Arguments passed on command line.
         3) Arguments passed to the C<run> method.
         4) Arguments passed via a conf file.
         5) Arguments set in the C<default_values> method.

       Additionally the following hooks are available:

         1) Arguments set in the configure_hook (occurs after new
            but before any of the other areas are checked).
         2) Arguments set and validated in the post_configure_hook
            (occurs after all of the other areas are checked).

       Each of these levels will override parameters of the same name speci-
       fied in subsequent levels.  For example, specifying --setsid=0 on the
       command line will override a value of "setsid 1" in the conf file.

       Note that the configure_hook method doesn’t return values to set, but
       is there to allow for setting up configured values before the configure
       method is called.

       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.

AADDDDIINNGG CCUUSSTTOOMM AARRGGUUMMEENNTTSS
       It is possible to add in your own custom parameters to those parsed by
       Net::Server.  The following code shows how this is done:

           sub options {
               my $self     = shift;
               my $prop     = $self->{’server’};
               my $template = shift;

               ### setup options in the parent classes
               $self->SUPER::options($template);

               ### add a single value option
               $prop->{’my_option’} ││= undef;
               $template->{’my_option’} = \ $prop->{’my_option’};

               ### add a multi value option
               $prop->{’an_arrayref_item’} ││= [];
               $template->{’an_arrayref_item’} = $prop->{’an_arrayref_item’};
           }

       Overriding the "options" method allows for adding your own custom
       fields.  A template hashref is passed in, that should then be modified
       to contain an of your custom fields.  Fields which are intended to
       receive a single scalar value should have a reference to the destina-
       tion scalar given.  Fields which are intended to receive multiple val-
       ues should reference the corresponding destination arrayref.

       You are responsible for validating your custom options once they have
       been parsed.  The post_configure_hook is a good place to do your vali-
       dation.

       Some emails have asked why we use this "template" method.  The idea is
       that you are creating the the data structure to store the values in,
       and you are also creating a way to get the values into the data struc-
       ture.  The template is the way to get the values to the servers data
       structure.  One of the possibilities (that probably isn’t used that
       much) is that by letting you specify the mapping, you could build a
       nested data structure - even though the passed in arguments are flat.
       It also allows you to setup aliases to your names.

       For example, a basic structure might look like this:

          $prop = $self->{’server’}

          $prop->{’my_custom_option’} ││= undef;
          $prop->{’my_custom_array’}  ││= [];

          $template = {
             my_custom_option => \ $prop->{’my_custom_option’},
             mco              => \ $prop->{’my_custom_option’}, # alias
             my_custom_array  => $prop->{’my_custom_array’},
             mca              => $prop->{’my_custom_array’}, # an alias
          };

          $template->{’mco2’} = $template->{’mco’}; # another way to alias

       But you could also have more complex data:

          $prop = $self->{’server’};

          $prop->{’one_layer’} = {
              two_layer => [
                  undef,
                  undef,
              ],
          };

          $template = {
               param1 => \ $prop->{’one_layer’}->{’two_layer’}->[0],
               param2 => \ $prop->{’one_layer’}->{’two_layer’}->[1],
          };

       This is of course a contrived example - but it does show that you can
       get the data from the flat passed in arguments to whatever type of
       structure you need - with only a little bit of effort.

DDEEFFAAUULLTT AARRGGUUMMEENNTTSS FFOORR NNeett::::SSeerrvveerr
       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    (native│unix│inet│udp
                            │tcp│stream│console)    unix (on Sys::Syslog < 0.15)
         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
         cidr_allow        CIDR                     none
         cidr_deny         CIDR                     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│SSLeay│etc)
         ## for more sample parameters.

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

           There are two ways that you can specify a default location for a
           conf_file.  The first is to pass the default value to the run
           method as in:

               MyServer->run({
                  conf_file => ’/etc/my_server.conf’,
               });

           If the end user passes in --conf_file=/etc/their_server.conf then
           the value will be overridden.

           The second way to do this was added in the 0.96 version.  It uses
           the default_values method as in:

               sub default_values {
                   return {
                       conf_file => ’/etc/my_server.conf’,
                   }
               }

           This method has the advantage of also being able to be overridden
           in the run method.

           If you do not want the user to be able to specify a conf_file at
           all, you can pass conf_file to the new method when creating your
           object:

               MyServer->new({
                  conf_file => ’/etc/my_server.conf’,
               })->run;

           If passed this way, the value passed to new will "win" over any of
           the other passed in values.

       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 "sys-
           log_logsock", "syslog_ident", and "syslog_logopt",and "sys-
           log_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, inet, native, console, stream, udp, or tcp, or an
           arrayref of the types to try.  Default is "unix" if the version of
           Sys::Syslog < 0.15 - otherwise the default is to not call setlog-
           sock.

           See Sys::Syslog.

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

       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 Sys::Syslog.

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

       port
           See Net::Server::Proto.  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 _h_o_s_t
           represents a hostname residing on the local box, where _p_o_r_t repre-
           sents either the number of the port (eg. "80") or the service des-
           ignation (eg.  "http"), and where _p_r_o_t_o represents the protocol to
           be used.  See Net::Server::Proto.  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, _p_r_o_t_o will default to the "proto"
           specified in the arguments.  If "proto" is not specified there it
           will default to "tcp".  If _h_o_s_t is not specified, _h_o_s_t will default
           to "host" specified in the arguments.  If "host" is not specified
           there it will default to "*".  Default port is 20203.  Configura-
           tion passed to new or run may be either a scalar containing a sin-
           gle port number or an arrayref of ports.

           On systems that support it, a port value of 0 may be used to ask
           the OS to auto-assign a port.  The value of the auto-assigned port
           will be stored in the NS_port property of the
           Net::Server::Proto::TCP object and is also available in the sock-
           port method.  When the server is processing a request, the
           $self->{server}->{sockport} property contains the port that was
           connected through.

       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 Net::Server::Proto. See IO::Socket.  Configuration
           passed to new or run may be either a scalar containing a single
           host or an arrayref of hosts - if the hosts array is shorter than
           the ports array, the last host entry will be used to augment the
           hosts arrary to the size of the ports array.

       proto
           See Net::Server::Proto.  Protocol to use when binding ports.  See
           IO::Socket.  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).  Configuration
           passed to new or run may be either a scalar containing a single
           proto or an arrayref of protos - if the protos array is shorter
           than the ports array, the last proto entry will be used to augment
           the protos arrary to the size of the ports array.

       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.  Infor-
           mation 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.

       cidr_allow/cidr_deny
           May be specified multiple times.  Contains a CIDR block to compare
           to incoming peeraddr.  If cidr_allow or cidr_deny options are
           given, the incoming client must match a cidr_allow and not match a
           cidr_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 ter-
           minal.

       no_close_by_child
           Boolean.  Specifies whether or not a forked child process has per-
           mission 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).

       no_client_stdout
           Boolean.  Default undef (not set).  Specifies that STDIN and STDOUT
           should not be opened on the client handle once a connection has
           been accepted.  By default the Net::Server will open STDIN and STD-
           OUT on the client socket making it easier for many types of scripts
           to read directly from and write directly to the socket using normal
           print and read methods.  Disabling this is useful on clients that
           may be opening their own connections to STDIN and STDOUT.

           This option has no affect on STDIN and STDOUT which has a magic
           client property that is tied to the already open STDIN and STDOUT.

       leave_children_open_on_hup
           Boolean.  Default undef (not set).  If set, the parent will not
           attempt to close child processes if the parent receives a SIG HUP.
           The parent will rebind the the open port and begin tracking a fresh
           set of children.

           Children of a Fork server will exit after their current request.
           Children of a Prefork type server will finish the current request
           and then exit.

           Note - the newly restarted parent will start up a fresh set of
           servers on fork servers.  The new parent will attempt to keep track
           of the children from the former parent but custom communication
           channels (open pipes from the child to the old parent) will no
           longer be available to the old child processes.  New child pro-
           cesses will still connect properly to the new parent.

       tie_client_stdout
           Default undef.  If set will use Net::Server::TiedHandle tied inter-
           face for STDIN and STDOUT.  This interface allows SSLEAY to work.
           It also allows for intercepting read and write via the
           tied_stdin_callback and tied_stdout_callback.

       tied_stdin_callback
           Default undef.  Called during a read of STDIN data if
           tie_client_stdout has been set, or if the client handle’s tie_std-
           out method returns true.  It is passed the client connection, the
           name of the method that would be called, and the arguments that are
           being passed.  The callback is then responsible for calling that
           method on the handle or for performing some other input operation.

       tied_stdout_callback
           Default undef.  Called during a write of data to STDOUT if
           tie_client_stdout has been set, or if the client handle’s tie_std-
           out method returns true.  It is passed the client connection, the
           name of the method that would be called, and the arguments that are
           being passed.  The callback is then responsible for calling that
           method on the handle or for performing some other output operation.

PPRROOPPEERRTTIIEESS
       All of the "ARGUMENTS" listed above become properties of the server
       object under the same name.  These properties, as well as other inter-
       nal 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 -
       though some would deem this as bad style.  A second way has been pro-
       vided 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 connec-
       tion).

CCOONNFFIIGGUURRAATTIIOONN FFIILLEE
       "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 blank lines 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.+
         cidr_allow  127.0.0.0/8
         cidr_allow  192.0.2.0/24
         cidr_deny   192.0.2.4/30

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

PPRROOCCEESSSS FFLLOOWW
       The process flow is written in an open, easy to override, easy to hook,
       fashion.  The basic flow is shown below.  This is the flow of the
       "$self->run" method.

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

         $self->post_client_connection_hook;

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

         $self->shutdown_sockets;

         $self->server_exit;

MMAAIINN SSEERRVVEERR MMEETTHHOODDSS
       "$self->run"
           This method incorporates the main process flow.  This flow is
           listed above.

           The method run may be called in any of the following ways.

              MyPackage->run(port => 20201);

              MyPackage->new({port => 20201})->run;

              my $obj = bless {server=>{port => 20201}}, ’MyPackage’;
              $obj->run;

           The ->run method should typically be the last method called in a
           server start script (the server will exit at the end of the ->run
           method).

       "$self->configure"
           This method attempts to read configurations from the commandline,
           from the run method call, or from a specified conf_file (the
           conf_file may be specified by passed in parameters, or in the
           default_values).  All of the configured parameters are then stored
           in the {"server"} property of the Server object.

       "$self->post_configure"
           The post_configure hook begins the startup of the server.  During
           this method running server instances are checked for, pid_files are
           created, log_files are created, Sys::Syslog is initialized (as
           needed), process backgrounding occurs and the server closes STDIN
           and STDOUT (as needed).

       "$self->pre_bind"
           This method is used to initialize all of the socket objects used by
           the server.

       "$self->bind"
           This method actually binds to the inialized sockets (or rebinds if
           the server has been HUPed).

       "$self->post_bind"
           During this method priveleges are dropped.  The INT, TERM, and QUIT
           signals are set to run server_close.  Sig PIPE is set to IGNORE.
           Sig CHLD is set to sig_chld.  And sig HUP is set to call sig_hup.

           Under the Fork, PreFork, and PreFork simple personalities, these
           signals are registered using Net::Server::SIG to allow for safe
           signal handling.

       "$self->loop"
           During this phase, the server accepts incoming connections.  The
           behavior of how the accepting occurs and if a child process handles
           the connection is controlled by what type of Net::Server personal-
           ity the server is using.

           Net::Server and Net::Server single accept only one connection at a
           time.

           Net::Server::INET runs one connection and then exits (for use by
           inetd or xinetd daemons).

           Net::Server::MultiPlex allows for one process to simultaneously
           handle multiple connections (but requires rewriting the pro-
           cess_request code to operate in a more "packet-like" manner).

           Net::Server::Fork forks off a new child process for each incoming
           connection.

           Net::Server::PreForkSimple starts up a fixed number of processes
           that all accept on incoming connections.

           Net::Server::PreFork starts up a base number of child processes
           which all accept on incoming connections.  The server throttles the
           number of processes running depending upon the number of requests
           coming in (similar to concept to how Apache controls its child pro-
           cesses in a PreFork server).

           Read the documentation for each of the types for more information.

       "$self->server_close"
           This method is called once the server has been signaled to end, or
           signaled for the server to restart (via HUP),  or the loop method
           has been exited.

           This method takes care of cleaning up any remaining child pro-
           cesses, setting appropriate flags on sockets (for HUPing), closing
           up logging, and then closing open sockets.

           Can optionally be passed an exit value that will be passed to the
           server_exit call.

       "$self->server_exit"
           This method is called at the end of server_close.  It calls exit,
           but may be overridden to do other items.  At this point all ser-
           vices should be shut down.

           Can optionally be passed an exit value that will be passed to the
           exit call.

MMAAIINN CCLLIIEENNTT CCOONNNNEECCTTIIOONN MMEETTHHOODDSS
       "$self->run_client_connection"
           This method is run after the server has accepted and received a
           client connection.  The full process flow is listed above under
           PROCESS FLOWS.  This method takes care of handling each client con-
           nection.

       "$self->post_accept"
           This method opens STDIN and STDOUT to the client socket.  This
           allows any of the methods during the run_client_connection phase to
           print directly to and read directly from the client socket.

       "$self->get_client_info"
           This method looks up information about the client connection such
           as ip address, socket type, and hostname (as needed).

       "$self->allow_deny"
           This method uses the rules defined in the allow and deny configura-
           tion parameters to determine if the ip address should be accepted.

       "$self->process_request"
           This method is intended to handle all of the client communication.
           At this point STDIN and STDOUT are opened to the client, the ip
           address has been verified.  The server can then interact with the
           client connection according to whatever API or protocol the server
           is implementing.  Note that the stub implementation uses STDIN and
           STDOUT and will not work if the no_client_stdout flag is set.

           This is the main method to override.

           The default method implements a simple echo server that will repeat
           whatever is sent.  It will quit the child if "quit" is sent, and
           will exit the server if "exit" is sent.

       "$self->post_process_request"
           This method is used to clean up the client connection and to handle
           any parent/child accounting for the forking servers.

HHOOOOKKSS
       "Net::Server" provides a number of "hooks" allowing for servers layered
       on top of "Net::Server" to respond at different levels of execution
       without having to "SUPER" class the main built-in methods.  The place-
       ment of the hooks can be seen in the PROCESS FLOW section.

       Almost all of the default hook methods do nothing.  To use a hook you
       simply need to override the method in your subclass.  For example to
       add your own post_configure_hook you could do something like the fol-
       lowing:

           package MyServer;

           sub post_configure_hook {
               my $self = shift;
               my $prop = $self->{’server’};

               # do some validation here
           }

       The following describes the hooks available in the plain Net::Server
       class (other flavors such as Fork or PreFork have additional hooks).

       "$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 config-
           urability.

       "$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->can_read_hook()"
           This hook occurs after a socket becomes readible on an
           accept_multi_port request (accept_multi_port is used if there are
           multiple bound ports to accept on, or if the "multi_port" configu-
           ration parameter is set to true).  This hook is intended to allow
           for processing of arbitrary handles added to the IO::Select used
           for the accept_multi_port.  These handles could be added during the
           post_bind_hook.  No internal support is added for processing these
           handles or adding them to the IO::Socket.  Care must be used in how
           much occurs during the can_read_hook as a long response time will
           result in the server being susceptible to DOS attacks.  A return
           value of true indicates that the Server should not pass the readi-
           ble handle on to the post_accept and process_request phases.

           It is generally suggested that other avenues be pursued for sending
           messages via sockets not created by the Net::Server.

       "$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->post_client_connection_hook"
           This is one final hook that occurs at the very end of the
           run_client_connection method.  At this point all other methods and
           hooks that will run during the run_client_connection have finished
           and the client connection has already been closed.

           item "$self->other_child_died_hook($pid)"

           Net::Server takes control of signal handling and child process
           cleanup; this makes it difficult to tell when a child process ter-
           minates if that child process was not started by Net::Server
           itself.  If Net::Server notices another child process dying that it
           did not start, it will fire this hook with the PID of the termi-
           nated process.

       "$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 sug-
           gested that it simply return and use the built in shut down fea-
           tures.

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

OOTTHHEERR MMEETTHHOODDSS
       "$self->default_values"
           Allow for returning configuration values that will be used if no
           other value could be found.

           Should return a hashref.

               sub default_values {
                 return {
                   port => 20201,
                 };
               }

       "$self->handle_syslog_error"
           Called when log_file is set to ’Sys::Syslog’ and an error occurs
           while writing to the syslog.  It is passed two arguments, the value
           of $@, and an arrayref containing the arguments that were passed to
           the log method when the error occured.

       "$self->log"
           Parameters are a log_level and a message.

           If log_level is set to ’Sys::Syslog’, the parameters may alter-
           nately be a log_level, a format string, and format string parame-
           ters.  (The second parameter is assumed to be a format string if
           additional arguments are passed along).  Passing arbitrary format
           strings to Sys::Syslog will allow the server to be vulnerable to
           exploit.  The server maintainer should make sure that any string
           treated as a format string is controlled.

               # assuming log_file = ’Sys::Syslog’

               $self->log(1, "My Message with %s in it");
               # sends "%s", "My Message with %s in it" to syslog

               $self->log(1, "My Message with %s in it", "Foo");
               # sends "My Message with %s in it", "Foo" to syslog

           If log_file is set to a file (other than Sys::Syslog), the message
           will be appended to the log file by calling the write_to_log_hook.

           If the log_file is Sys::Syslog and an error occurs during write,
           the handle_syslog_error method will be called and passed the error
           exception.  The default option of handle_syslog_error is to die -
           but could easily be told to do nothing by using the following code
           in your subclassed server:

               sub handle_syslog_error {}

           It the log had been closed, you could attempt to reopen it in the
           error handler with the following code:

               sub handle_syslog_error {
                 my $self = shift;
                 $self->open_syslog;
               }

       "$self->new"
           As of Net::Server 0.91 there is finally a new method.  This method
           takes a class name and an argument hashref as parameters.  The
           argument hashref becomes the "server" property of the object.

              package MyPackage;
              use base qw(Net::Server);

              my $obj = MyPackage->new({port => 20201});

              # same as

              my $obj = bless {server => {port => 20201}}, ’MyPackage’;

       "$self->open_syslog"
           Called during post_configure when the log_file option is set to
           ’Sys::Syslog’.  By default it use the parsed configuration options
           listed in this document.  If more custom behavior is desired, the
           method could be overridden and Sys::Syslog::openlog should be
           called with the custom parameters.

       "$self->shutdown_sockets"
           This method will close any remaining open sockets.  This is called
           at the end of the server_close method.

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

       The Net::Server will attempt to find out the commandline used for
       starting the program.  The attempt is made before any configuration
       files or other arguments are processed.  The outcome of this attempt is
       stored using the method "->commandline".  The stored commandline may
       also be retrieved using the same method name.  The stored contents will
       undoubtedly contain Tainted items that will cause the server to die
       during a restart when using the -T flag (Taint mode).  As it is impos-
       sible to arbitrarily decide what is taint safe and what is not, the
       individual program must clean up the tainted items before doing a
       restart.

         sub configure_hook{
           my $self = shift;

           ### see the contents
           my $ref  = $self->commandline;
           use Data::Dumper;
           print Dumper $ref;

           ### arbitrary untainting - VERY dangerous
           my @untainted = map {/(.+)/;$1} @$ref;

           $self->commandline(\@untainted)
         }

FFIILLEESS
       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

IINNSSTTAALLLL
       Download and extract tarball before running these commands in its base
       directory:

           perl Makefile.PL
           make
           make test
           make install

AAUUTTHHOORR
       Paul Seamons <paul at seamons.com>

TTHHAANNKKSS
       Thanks to Rob Brown (bbb at cpan.org) for help with miscellaneous con-
       cepts 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 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 seri-
       alize argument in the PreFork server.

       Thanks to _t_r_a_v_e_l_e_r and _m_e_r_l_y_n 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 sugges-
       tions and for work on Net::Server::Daemonize.

       Thanks to Vadim <vadim at hardison.net> for patches to implement par-
       ent/child communication on PreFork.pm.

       Thanks to Carl Lewis for suggesting "-" in user names.

       Thanks to Slaven Rezic for suggesing Reuse => 1 in Proto::UDP.

       Thanks to Tim Watt for adding udp_broadcast to Proto::UDP.

       Thanks to Christopher A Bongaarts for pointing out problems with the
       Proto::SSL implementation that currently locks around the socket accept
       and the SSL negotiation. See Net::Server::Proto::SSL.

       Thanks to Alessandro Zummo for pointing out various bugs including some
       in configuration, commandline args, and cidr_allow.

       Thanks to various other people for bug fixes over the years.  These and
       future thank-you’s are available in the Changes file as well as CVS
       comments.

       Thanks to Ben Cohen and tye (on Permonks) for finding and diagnosing
       more correct behavior for dealing with re-opening STDIN and STDOUT on
       the client handles.

       Thanks to Mark Martinec for trouble shooting other problems with STDIN
       and STDOUT (he proposed having a flag that is now the no_client_stdout
       flag).

       Thanks to David (DSCHWEI) on cpan for asking for the nofatal option
       with syslog.

       Thanks to Andreas Kippnick and Peter Beckman for suggesting leaving
       open child connections open during a HUP (this is now available via the
       leave_children_open_on_hup flag).

       Thanks to LUPE on cpan for helping patch HUP with taint on.

       Thanks to Michael Virnstein for fixing a bug in the check_for_dead sec-
       tion of PreFork server.

       Thanks to Rob Mueller for patching PreForkSimple to only open lock_file
       once during parent call.  This patch should be portable on systems sup-
       porting flock.  Rob also suggested not closing STDIN/STDOUT but instead
       reopening them to /dev/null to prevent spurious warnings.  Also sug-
       gested short circuit in post_accept if in UDP.  Also for cleaning up
       some of the child managment code of PreFork.

       Thanks to Mark Martinec for suggesting additional log messages for
       failure during accept.

       Thanks to Bill Nesbitt and Carlos Velasco for pointing out double
       decrement bug in PreFork.pm (rt #21271)

       Thanks to John W. Krahn for pointing out glaring precended with non-
       parened open and ││.

       Thanks to Ricardo Signes for pointing out setuid bug for perl 5.6.1 (rt
       #21262).

       Thanks to Carlos Velasco for updating the Syslog options (rt #21265).
       And for additional fixes later.

       Thanks to Steven Lembark for pointing out that no_client_stdout wasn’t
       working with the Multiplex server.

       Thanks to Peter Beckman for suggesting allowing Sys::SysLog keyworks be
       passed through the ->log method and for suggesting we allow more types
       of characters through in syslog_ident.  Also to Peter Beckman for
       pointing out that a poorly setup localhost will cause tests to hang.

       Thanks to Curtis Wilbar for pointing out that the Fork server called
       post_accept_hook twice.  Changed to only let the child process call
       this, but added the pre_fork_hook method.

       And just a general Thanks You to everybody who is using Net::Server or
       who has contributed fixes over the years.

       Thanks to Paul Miller for some ->autoflush, FileHandle fixes.

       Thanks to Patrik Wallstrom for suggesting handling syslog errors bet-
       ter.

       Thanks again to Rob Mueller for more logic cleanup for child accounting
       in PreFork server.

       Thanks to David Schweikert for suggesting handling setlogsock a little
       better on newer versions of Sys::Syslog (>= 0.15).

       Thanks to Mihail Nasedkin for suggesting adding a hook that is now
       called post_client_connection_hook.

       Thanks to Graham Barr for adding the ability to set the check_for_spawn
       and min_child_ttl settings of the PreFork server.

       Thanks to Daniel Kahn Gillmor for adding the other_child_died_hook.

       Thanks to Dominic Humphries for helping not kill pid files on HUP.

       Thanks to Kristoffer Møllerhøj for fixing UDP on Multiplex.

SSEEEE AALLSSOO
       Please see also Net::Server::Fork, Net::Server::INET, Net::Server::Pre-
       ForkSimple, Net::Server::PreFork, Net::Server::MultiType,
       Net::Server::Single Net::Server::HTTP

TTOODDOO
         Improve test suite to fully cover code (using Devel::Cover).  Anybody
         that wanted to send me patches to the t/*.t tests that improved coverage
         would earn a big thank you :) (Sorry there isn’t a whole lot more than that to give).

AAUUTTHHOORR
         Paul Seamons <paul at seamons.com>
         http://seamons.com/

         Rob Brown <bbb at cpan.org>

LLIICCEENNSSEE
       This package may be distributed under the terms of either the

         GNU General Public License
           or the
         Perl Artistic License

       All rights reserved.



perl v5.8.8                       2011-07-22                         SERVER(1)
