POUND - REVERSE-PROXY AND LOAD-BALANCER

The Pound program is a reverse proxy, load balancer and
HTTPS front-end for Web server(s). Pound was developed
to enable distributing the load among several Web-servers
and to allow for a convenient SSL wrapper for those Web
servers that do not offer it natively. Pound is distributed
under the GPL - no warranty, it's free to use, copy and
give away.

WHAT POUND IS:

1.  a reverse-proxy: it passes requests from client
    browsers to one or more back-end servers.

2.  a load balancer: it will distribute the requests from
    the client browsers among several back-end servers,
    while keeping session information.

3.  an SSL wrapper: Pound will decrypt HTTPS requests
    from client browsers and pass them as plain HTTP
    to the back-end servers.

4.  an HTTP/HTTPS sanitizer: Pound will verify requests
    for correctness and accept only well-formed ones.

5.  a fail over-server: should a back-end server fail,
    Pound will take note of the fact and stop passing
    requests to it until it recovers.

6.  a request redirector: requests may be distributed
    among servers according to the requested URL.

Pound is a very small program, easily audited for security
problems. It can run as setuid/setgid and/or in a chroot
jail. Pound does not access the hard-disk at all (except
for reading certificate file(s) on start, if required)
and should thus pose no security threat to any machine.

WHAT POUND IS NOT:

1.  Pound is not a Web server: by itself, Pound serves no
    content - it contacts the back-end server(s) for that
    purpose.

2.  Pound is not a Web accelerator: no caching is done -
    every request is passed "as is" to a back-end server.

STATUS

As of release 1.0 Pound is declared to be production-quality code.

Quite a few people have reported using Pound successfully in production
environments. The largest volume reported to date is a site with an
average of about 30M requests per day, peaking at over 600 requests/sec.

Pound was successfully used in production with a variety of Web servers,
including Apache, IIS, Zope, WebLogic, Jakarta/Tomcat, iPlanet, etc. In
general Pound passes requests and responses back and forth unchanged,
so we have no reason to think that any web server would be incompatible.

Client browsers that were tested:

- IE 5.0/5.5 (Windows) HTTP/HTTPS

- Netscape 4.7 (Windows/Linux) HTTP/HTTPS

- Mozilla (Windows/Linux) HTTP/HTTPS

- Konqueror (Linux) HTTP/HTTPS

- Galleon (Linux) HTTP/HTTPS

- Opera (Linux/Windows) HTTP/HTTPS

- Lynx (Linux) HTTP

Given that Pound is in production and no problems were reported, we have
no reason to believe that other browsers would present a problem. A few
issues were observed with problematic SSL implementations, most notably
with Opera 6, but these should be OK in the present version.

INSTALLATION

Probably the easiest way to install Pound is to use a pre-compiled package
if you can find one. While Apsis offers no such packages, they are available
for quite a few systems (Suse, Debian and derivatives such as Ubuntu), as
well as some private packages:

- RPMs for RedHat are available at http://www.invoca.ch/pub/packages/pound/

- A nice FreeBSD live-CD distribution is available at http://www.targeted.org as
http://www.targeted.org/files/fbsd62_pound23.iso.gz, including a Pound binary.

Failing that you should install from sources:

1.  Pound was tested on Linux, Solaris and OpenBSD, but
    it should work unchanged on just about any modern
    Unix-like system. You will require at least OpenSSL and
    libpthread. The PCRE package is strongly recommended.

    Warning: as Pound is a multi-threaded program it requires
    a version of OpenSSL with thread support. This is normally
    the case on Linux and Solaris (for example) but not on *BSD.
    If your system has the wrong library please download, compile
    and install OpenSSL (from http://www.openssl.org).

    If the PCRE package is available Pound will link against it.
    This will provide a significant performance boost.

2.  Download the current version of Pound-current file and unpack
    it. The archive is signed.
    My signature is available at http://www.apsis.ch/pound/roseg.asc.
    Alternately see below for stable versions.

    Unpack. Do the usual thing:

        ./configure

3.  The following options are available for the configure script:

    --with-ssl=ssl_dir -- OpenSSL home directory (default: system defined).

    --disable-super -- disable supervisor process (default: enabled)

    --with-t_rsa=nnn   -- timeout of the RSA ephemeral keys regeneration
    (default: 1800 seconds).

    --with-owner=owner -- name of installed binaries owner (default is
    system-dependent).

    --with-group=group -- name of installed binaries group (default is
    system-dependent).

4.  Check that the resulting Makefile is correct and possibly
    adjust flags as needed on your system. Compile:

        make

5.  If it works, you may want to do some testing before installing.

6.  Install the executable somewhere (it's likely that
    /usr/local/sbin would make a good choice), as well
    as the manual page (pound.8 -> /usr/local/man/man8).
    The supplied Makefile will do it for you.

7.  Make sure Pound gets started on boot. Read the man
    page for available options and examples.

Pound is copyrighted by Apsis GmbH and is distributed under
the terms of the GNU Public License with the additional
exemption that compiling, linking, and/or using OpenSSL is
allowed. Basically, this means that you can use it free of
charge, copy it, distribute it (provided the copyright is
maintained and the full package is distributed), modify it,
or line a bird-cage with it.

We would be happy to hear from you if you use it and
suggestions and improvements are gladly accepted.

CONTACT

Robert Segall, roseg@apsis.ch

Apsis GmbH, http://www.apsis.ch

P O Box

CH-8707 Uetikon am See

Switzerland

+41-44-920 4904

MAILING LIST

Pound has its own mailing list now: please send a message with
the subject "subscribe" to pound@apsis.ch in order to
subscribe. You will receive confirmation and instructions in
the reply.

All messages are available and indexed (searcheable) in the
archive http://www.apsis.ch/pound/pound_list.

The mailing list is the primary support forum for Pound - please
post there any questions you may have. The developpers' address is
given here for information purposes only.

ZOPE

A special note for Zope users: the original intent on
developing Pound was to allow distributing the load
among several Zope servers running on top of ZEO. This
it does.

A special problem arises when you try using Pound as an
SSL wrapper: Zope assumes that the requests are made via
HTTP and insists on prepending 'http://' to the (correct)
address in the replies, including in the <base> tag and
the absolute URLs it generates (for images for example).
This is clearly an undesirable behavior.

For older Zope versions (prior to 2.7): a modified z2.py (as
well as a patch) is included in the distribution. The main
difference is that this z2.py allows starting an additional
HTTP server via the -y flag that sets the environment
HTTPS variable - thus correcting the problem. That means
that in order to use Pound as an SSL wrapper you need to:

- start Zope (modify the 'start' file) as:

    python -X -w 8080 -y 8443 ...

For Zope 2.7 or later the same effect can be achieved via suitable
modifications to zope.conf.

VIRTUAL HOSTS (IN GENERAL)

Some people asked about the possibility of redirecting requests to back-ends
as per some virtual hosts definition. While I believe this is not Pound's
job, it can be done. As of version 0.10, Pound supports filtering requests
based not only on the request URL, but also on the presence or absence of
certain headers.

Let's assume that you have internal server 192.168.0.10 that is supposed to
serve the needs of virtual host www.server0.com and 192.168.0.11 that serves
www.server1.com.  You want Pound to listen on address 1.2.3.4 and separate
the requests to each host.  The config file would look something like this:

    ListenHTTP
        Address 1.2.3.4
        Port    80

        Service
            HeadRequire "Host: .*www.server0.com.*"

            BackEnd
                Address 192.168.0.10
                Port    80
            End
        End

        Service
            HeadRequire "Host: .*www.server1.com.*"

            BackEnd
                Address 192.168.0.11
                Port    80
            End
        End
    End

(add whatever else is necessary) or, if you want even safer filtering:

    ListenHTTP
        Address 1.2.3.4
        Port    80

        Service
            HeadRequire "Host: .*www.server0.com.*"
            HeadDeny    "Host: .*www.server1.com.*"

            BackEnd
                Address 192.168.0.10
                Port    80
            End
        End

        Service
            HeadRequire "Host: .*www.server1.com.*"
            HeadDeny    "Host: .*www.server0.com.*"

            BackEnd
                Address 192.168.0.11
                Port    80
            End
        End
    End

This is NOT recommended (I personally believe

Pound

Install / Use

README