view release on metacpan or  search on metacpan

ProxyConf.pm  view on Meta::CPAN

  </Location>

=head1 DESCRIPTION

The Apache::ProxyConf is used to configure the proxy settings in browsers
automatically. The modules returns a script that conforms to the Navigator
Proxy Auto-Config File Format. The module is suitable for large scale
installations that have multiple (cascading) proxies. It can be used
to return 'the closest proxy' based on the network topology. Failover and
load distribution is also provided.

=head2 Browser configuration

The (virtual) webserver must be entered in the 'Autoconfigure URL' of the
browser to make use of the ProxyConf script.

http://proxyconf.some.domain/

In IE the URL must be specified in the 'Address' field, just below the
'Use automatic configuration script' tickbox.

=head1 THE CONFIGURATION FILE

The ProxyConf module first reads a .ini-style configuration file to determine
the proxy settings of the network. The configuration file contains three
sections: proxy, noproxy and https.

=head2 The proxy section

The sections proxy and https have an identical format. They contain lines of
the form C<subnet=proxyip:port>.

=over 4

=item Single proxy

 [proxy]
 172.16.32.0/20=172.16.32.10:3128

The subnet 172.16.32.0/20 has a single proxy defined. The proxy server is
172.16.32.10 and it listens on port 3128.

=item Multiple proxies

 [proxy]
 172.16.0.0/20=172.16.0.10:3128,172.16.0.20:3128

Multiple proxy servers are defined in a comma separated list. In this
example clients in the 172.16.0.0/20 subnet use 172.16.0.10 as their primary
proxy server. When this server becomes unavailable, the clients will move over
to 172.16.0.20 for their proxy requests.

=item Multiple proxies with load distribution

 [proxy]
 172.16.0.0/20=(172.16.0.10:3128,172.16.0.20:3128)

When proxy servers are placed between brackets, the load is distribution
amongst the proxies. Some clients will have the first proxy as primary and some
clients will have the second proxy as primary. The other proxy is used as a
backup. The order in which the proxies are tried depends on the IP address of
the client. The script is deterministic, so for a given IP address the
priority list is always the same. 

=back

To determine the proxy list for a given IP address multiple rules may be
applied. Subnets are tried from the highest to the lowest mask. The module
puts all proxies that are found in a list.

=head2 The noproxy section

The noproxy section contains hosts that should be contacted by the clients
directly. Noticeably, web servers that use NTLM authentication will not work
when clients connect to them via a proxy server. The syntax for specifying
noproxy hosts is C<subnet=fqhn1,fqhn2,..>. Alternatively, the multiline
syntax can be used, as shown in this example.

 [noproxy]
 0.0.0.0/0=<<EOT
 webserver1.some.domain
 webserver2.some.domain
 EOT

This section defines webservers that are non-proxyable for all networks.

=head2 The https section

The https section works like the proxy section. It is used to define
other proxies for secure HTTP traffic than for the normal HTTP traffic.
If this section is missing, or for a specific IP address
there are no https rules, then the normal proxy rules apply.

=head1 EXAMPLE

Consider the network in figure 1. 

          Network A: 172.16.0.0/20

             _.-"""""""""""""""""-._
           .'                       `.
          /                           \
        |    Proxy A1: 172.16.0.10    |
        |                             |
        |    Proxy A2: 172.16.0.20    |
         \                           /
          `._                     _.'\
             `-.................-'    \
                                       \
                                        \  Network B: 172.16.16.0/20
                                         \
                                          \ _.-"""""""""""""""""-._
                                          .'                       `.
                                         /                           \
                                        |                             |
                                        |    Proxy B: 172.16.16.10    |
                                        |                             |
                                         \                           /
                                          `._                     _.'
                                          /  `-.................-'
                                         /