View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Rob Brown > Net-DNAT-0.13 > Net::DNAT



Annotate this POD

View/Report Bugs
Module Version: 0.13   Source   Latest Release: Net-DNAT-0.15


Net::DNAT - Psuedo Layer7 Packet Processer


  use Net::DNAT;

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


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.



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 to switch to once the server starts. (Just used by Net::Server)

 Example: user => "nobody"


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

 Example: group => "nobody"


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 => "",
    dev => "",

 Example: pools => ""


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


Specify which hosts go to which pools.

 Example: host_switch_table => {
    "" => "www",
    "" => "dev",


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


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


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


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.


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


See INSTALL document.


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


  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.


  More information on network layers:


  Copyright (C) 2002-2003,
  Rob Brown,

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

  All rights reserved.


syntax highlighting: