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 the Net::Server manpage
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>