NAME
    Net::DNAT - Psuedo Layer7 Packet Processer

SYNOPSIS
      use Net::DNAT;

      run Net::DNAT <settings...>;

DESCRIPTION
    This module is intended to be used for testing applications designed for
    load balancing systems. It listens on specified ports and forwards the
    incoming connections to the appropriate remote applications. The remote
    application can be on a separate machine or on the same machine
    listening on a different port and/or address.

SETTINGS
  port
    Specify which port or ports to listen on. See Net::Server for more
    details on the port setting and other Net::Server settings which may
    also be used with Net::DNAT.

     Example: port => 80

  user
    User to switch to once the server starts. (Just used by Net::Server)

     Example: user => "nobody"

  group
    Group to switch to once the server starts. (Just used by Net::Server)

     Example: group => "nobody"

  pools
    Supply a hash ref of pool definitions. The key in the hash is the pool
    name. Its value is either one destination scalar or an array ref of one
    or more destinations. If you just specify the destination value instead
    of a hash ref, it will assume it is for the "default" pool and will also
    be used as "default_pool". Each destination may be an IP address, a
    single host, or a hostname of a round robin dns to several IP addresses.
    Each destination may be followed by an optional :port to specify which
    port to connect to. The default is http (port 80) if none is specified.

     Example: pools => {
        www => "web.server.com",
        dev => "dev.server.com",
      }

     Example: pools => "web.server.com"

  default_pool
    Specify which key in the pools hash ref should be used if no specific
    pool could be determined based on the request information. If only one
    pool is specified in the pools hash, that pool is assumed to be the
    default_pool.

     Example: default_pool => www

  host_switch_table
    Specify which hosts go to which pools.

     Example: host_switch_table => {
        "server.com" => "www",
        "test.com" => "dev",
      }

  switch_filters
    Supply special header modifications or provide ability to compute
    destination pool based on arbitrary code. It takes an array ref of
    destination pairs. The first in the pair is either a regex or a code
    ref. The second of the pair is the destination pool name from the pools
    setting. If a regex is used, the pool is determined if the regex passes
    when filtered through the header request block. If a code ref is used,
    $_ will contain the request header block. If executing the code ref
    returns a true value, its corresponding pool with be used. This is meant
    to be thought of as a hash ref, but the order must be preserved, and
    refs do not work very well as hash keys, so it uses an array ref
    instead. Be aware that any modifications to $_ will also be passed on to
    the destination regardless of whether the code ref returned a true value
    or not. Also, the switch_filters are run before to the
    host_switch_table.

     Example: switch_filters => [
        qr%^Cookie:.*magic%im => "dev",
        sub { s%^(Host: )www\.%$1%im; 0; } => "dev",
      ]

  connect_timeout
    Specify the maximum number of seconds that a destination node can take
    before it will be considered down. The default is 3 seconds.

     Example: connect_timeout => 10

  check_for_dequeue
    Net::DNAT can periodically perform service checks on the destination
    node of each pool. This setting specifies this interval in seconds. To
    disable these checks, set this to 0. The default is 60 seconds.

     Example: check_for_dequeue => 30

PEER SOCKET SPOOF
    This implementation does not actually translate the destination address
    in the packet headers and resend the packet, like true DNAT does. It is
    implemented like a port forwarding proxy. When a client connects, a new
    socket is made to the remote application and the connection is tunnelled
    to/from the client. This causes the peer side of the socket to appear to
    the remote application like it is coming from the Net::DNAT box instead
    of the real client. This peer modification side effect is usually fine
    for testing and developmental purposes, though.

HTTP
    If you do not care about where the hits on your web server are coming
    from, then you do not need to worry about this section. If the remote
    application is the Apache 1.3.x web server, ( see
    http://httpd.apache.org/ ), then the Apache::DNAT module can be used to
    correctly and seemlessly UnDNATify this peer munging described above. If
    mod_perl is enabled for Apache, then add this line to its httpd.conf:

      PerlModule Apache::DNAT
      PerlInitHandler Apache::DNAT

    If you cannot do this, (because it is a web server other than Apache, or
    you do not have mod_perl enabled, or you do not have access to the web
    server, or you just do not want the CPU overhead to fix the peer back to
    normal, or for whatever reason), then it will still function fine. Just
    the server logs will be inaccurate and the CGI programs will run with
    the wrong environment variables pertaining to the peer (i.e.,
    REMOTE_ADDR and REMOTE_PORT).

INSTALL
    See INSTALL document.

EXAMPLES
    See demo/* from the distribution for some working examples.

TODO
      Test suite example using server and client though Net::DNAT.
      Test suite example using client and pool of servers.
      Test suite example using Apache::DNAT.
      Support for HTTP/1.1 protocol conversion to 1.0 protocol and back again.
      Support for HTTP/1.1 KeepAlive timeout and KeepAliveRequests.
      Support for SSL conversion to plain text and back (IO::Multiplex).
      Support for html error pages for internal errors like Server outages.
      Support for error logs.
      Support for access logs.
      Support for CVS protocol.
      Support for FTP protocol.
      Support for OOB channel data correctly.
      Support for DNS protocol.

LAYER
      More information on network layers:

      http://uwsg.iu.edu/usail/network/nfs/network_layers.html

COPYRIGHT
      Copyright (C) 2002-2003,
      Rob Brown, bbb@cpan.org

      This package may be distributed under the same terms as Perl itself.

      All rights reserved.

SEE ALSO
     L<Apache::DNAT>,
     L<Net::Server>,
     L<IO::Multiplex>

