David
Maucher

WordPress expert
Web Developer

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 the certificate file 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:

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 Apse offers no such packages, they are available for quite a few systems (SuSE Linux, Debian and derivatives such as Ubuntu, as well as some private packages:

Please note that these sites are not affiliated with Apseand we are not responsible for the contents.

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 OpenSSL and the native threads library. The PCRE package and the tcmalloc (or Hoard) libraries are 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) with threads supportIf the PCRE, tcmalloc (from the Google perftools package) and/or Hoard are available Pound will link against them. This will provide a significant performance boost and is high recommended.
  2. Download the latest version Pound-2.8.tgz file and unpack it. The archive is signed.my signature is available here.alternatively see below for experimental versions.
  3. Unpack. Do the usual thing: ./configure
  4. The following options are available for the configure script: -with-ssl=ssl_dir - OpenSSL home directory -disable-super - disable supervisor process (default: enabled) -with-t_rsa=nnn - timeout of the RSA ephemeral keys regeneration (default: 30 minutes). -with-owner=owner - name of installed binaries owner (default is system-dependent). -with-group=group - name of installed binaries group (default is system-dependent). -with-dh=nnn - size of the support DH keys (1024/2048)
  5. Check that the resulting Makefile is correct and possibly adjust flags as needed on your system. Compile: make
  6. If it works, you may want to do some testing before installing.
  7. 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.
  8. Make sure Pound gets started on boot. Read the man page for available options and examples.

COPYRIGHT

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.

MAILING LIST

Pound has its own mailing list now: please send a message in order to subscribe. You will receive confirmation and instructions in the reply.

All messages are available and indexed (searcheable) in the archive.

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.

LOGO

If you use Pound we would appreciate your indicating this by adding the logo to your pages, with a link to the Pound

Heartbleed

We had quite a few questions about Heartbleed mitigation. Pound can't do much about it - Heartbleed is an OpenSSL issue. To ensure that you are not vulnerable please update your OpenSSL library to a secure version.

In most cases Pound is dinamically linked against OpenSSL. On Linux systems you can use the ldd command to check what libraries are linked dynamically against a binary. After updating the library just stop and restart Pound to make sure it uses the correct version.

In those rare cases where Pound is statically linked against OpenSSL you will need to obtain a new compiled version of Pound, or recompile it yourself. In any case a Pound restart will be necessary.

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 tag and the absolute URLs it generates (for images for example). This is clearly an undesirable behavior.

In order to address this issue, 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:

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 End This is NOT recommended (I personally believe that virtual hosts should be implemented in the back-end servers - putting this in a proxy is a major security kludge) but it works.

VIRTUAL HOSTS AND HTTPS

Quite often we get inquiries about Pound's ability to do virtual hosting with HTTPS. In order to lay this matter to rest, let me say:HTTPS does not allow virtual hosting This is not a limitation of Poundbut of HTTPS - no Web server or proxy are able to do it due to the nature of the beast.

In order to see why this is the case we need to look at the way HTTPS works. Basically there are three stages in any HTTPS connection:

  1. Connection negotiation - the client (your browser) and the server (Web server or proxy) negotiate the basic parameters: ciphers to use, session key, etc.
  2. Connection authentication: at the very least the server presents the client with a certificate that says "I am server www.encrypted.com - and certificate.authority.org will verify that". The client may also present a certificate of its own at this stage.
  3. Request/response cycle: normal HTTP is sent (through the encrypted channel) back and forth.

The vital point to notice here is that connection authentication takes place BEFORE any request was issued.

On the other hand, the way virtual hosting works is for the client to specify in the request to which server it would like to talk. This is accomplished via a Host header: GET /index.html HTTP/1.1 Host: http://www.virthost.com Combining the two we get to an impasse: on connection setup the server will reply with the certificate for "www.realhost.com", but the request is really for "www.virthost.com" - and most browsers will scream blue murder (as well they should) if the two do not match.

There is a new twist on this however: some of the newer browsers will accept so-called "wild-card certificates". This is a specially crafted certificate that is not issued to a host, but rather to a domain. The result is that on setting-up a new SSL connection, the server replies not with "I am www.encrypted.com", but with "I am *.encrypted.com". If the browser is capable of processing this type of certificate then the connection is set up and normal HTTPS (with www.encrypted.com or special.encrypted.com or even some.other.server.encrypted.com or whatever other name matches) proceeds as usual. Pound supports these certificates and you can use virtual hosts in the normal way.

Update June 2010Starting with the 2.6 series, Pound has SNI support, if your OpenSSL version supports it. Basically you supply Pound with several certificates, one for each virtual host (wild card certificates - as described above - are allowed). On connecting the client signals to which server it wants to talk, and Pound searches among its certificates which would fit. Not all versions of OpenSSL and not all clients WordPress support this mode, but if available it allows for virtual hosts over HTTPS.

An additional option is to use a semi-official TLS extension, the so-called alternate subject name. If your version of OpenSSL supports it you may specify in one certificate several alternate server names. This requires support for a special TLS feature, and nor all clients accept it.

VIRTUAL HOSTS IN ZOPE

For reasons I can't quite grasp, it seems that a lot of Zope users are convinced that virtual hosts are only possible through the Apache/VHM combination and that it requires some kind of magic incantation at midnight in order to work (I won't even start on the virgin sacrifices).

The simple fact is that VHM and the Apache VirtualHost directives (as well as various tricks through mod_rewrite and mod_proxy) are (almost) mutually exclusive: they perform exactly the same functions and, leaving aside the logging issues, are used independently of each other. Let me repeat that: you may use the VHM without Apache - just click on the VHM mappings tab and add whatever virtual host you wish. From this moment on any request to that host will be mapped back and forth by Zope to the required URL. This works if you access Zope directly or via any number of proxies on the way, Pound included.

To test: add a new host name to your /etc/hosts file, making it an alias for localhost - something like: 127.0.0.1 localhost www.testhost.mine Add a mapping in VHM from www.testhost.mine to some Zope folder (Examples is already there). Point your browser to http://localhost and you get the normal Zope start page; point it to http://www.testhost.mine and you'll see the Examples starting page. All requests are mapped correctly, and the URLs in the pages (such as base or absoluteURL) are translated correctly in the response.

SESSIONS

Pound has the ability to keep track of sessions between a client browser and a back-end server. Unfortunately, HTTP is defined as a stateless protocol, which complicates matters: many schemes have been invented to allow keeping track of sessions, none of which works perfectly. Even worse, sessions are critical in order to allow web-based applications to function correctly - it is vital that once a session is established all subsequent requests from the same browser be directed to the same back-end server.

Six possible ways of detecting a session have been implemented in Pound (hopefully the most useful ones): by client address, by Basic authentication, by URL parameter, by cookie, by HTTP parameter and by header value.

Please note the following restrictions on session tracking:

A note on cookie injection: some applications have no session-tracking mechanism at all but would still like to have the client always directed to the same back-end time after time. Some reverse proxies use a mechanism called "cookie injection" in order to achieve this: a cookie is added to the back-end responses and tracked by the reverse proxy.

Pound was designed to be as transparent as possible, and this mechanism is not supported. If you really need this sort of persistent mapping use the client address session mechanism (Session Type IP), which achieves the same result without changing the contents in any way.

REQUEST LOGGING

As a general rule, Pound passes all headers as they arrive from the client browser to the back-end server(s). There are two exceptions to this rule: Pound may add information about the SSL client certificate (as described below), and it will add an X-Forwarded-For header. The general format is: X-Forwarded-for: client-IP-address The back-end server(s) may use this extra information in order to create their log-files with the real client address (otherwise all requests will appear to originate from Pound itself, which is rather useless).

In addition, Pound logs requests and replies to the system log. This is controlled by the LogLevel configuration variable (0 - no logging, 1 - normal log, 2 - full log, 3 - Apache combined log format, 4 - Apache combined log format without virtual host).

By default the messages go to the LOG_DAEMON facility, but you can change this in the configuration. If you don't want to, you can just do a: fgrep pound /var/log/messages to get all the messages generated by Pound.

HTTPS CERTIFICATES

If a client browser connects via HTTPS and if it presents a certificate and if HTTPSHeaders is set, Pound will obtain the certificate data and add the following HTTP headers to the request it makes to the server:

It is the application's responsibility to actually use these headers - Pound just passes this information without checking it in any way (except for signature and encryption correctness).

Please note that this mechanism allows forgeries: a client may (maliciously) send these headers to Pound in order to masquerade as an SSL client with a specific certificate. If this is a problem for your application make sure to deny these requests. Add: HeadDeny X-SSL-Subject ".*" HeadDeny X-SSL-Issuer ".*" HeadDeny X-SSL-notBefore ".*" HeadDeny X-SSL-notAfter ".*" HeadDeny X-SSL-serial ".*" HeadDeny X-SSL-cipher ".*" within the UrlGroup(s).

THREADS AND LIMITS

A few people ran into problems when installing Pound because of the various threading models and how they interact with system-imposed limits. Please keep in mind the following requirements:

Please note that your kernel needs to be configured to support the required resources - the above are just the shell commands.

SIMILAR SYSTEMS

Quite a few people asked "What is wrong with Apache/Squid/stunnel/your_favorite? Do we really need another proxy system?". The simple answer is that there is nothing wrong - they are all excellent systems that do their jobs very well. The reasoning behind Pound is however slightly different:

Taking these criteria into consideration, it is easy to see why the other systems mentioned above do not fit:

DEDICATED SERVERS

Some people asked about the possibility of dedicating specific back-end servers to some clients - in other words, if a request originates from a certain IP address or group of addresses then it should be sent to a specific group of back-end servers.

Given the ease with which IP addresses can be forged I am personally doubtful of the utility of such a feature. Even should you think it desirable, it is probably best implemented via the packet filter, rather than a proxy server. Assuming that requests from x.com are to go to s1.local, requests from y.com to s2.local and everything else to s3.local and s4.local, here is how to do it:

This would give you the desired effect and probably better performance than a purely proxy-based solution (though the performance improvement is debatable, at least on Linux).

WebDAV

As of version 1.0 Pound supports the full WebDAV command-set. In fact, it has been tested and is known to (almost) work with the Microsoft Outlook Web Gateway, which is quite remarkable given that Microsoft's own proxy does not.

Regrettably, Microsoft adherence to standards leaves something to be desired: they decided to add some characters to their URLs - thus breaking a whole set of RFC's.

Rather then change Pound to accept these characters (which could create some serious issues with security on other systems) we have made this behavior dependent on a configuration switch: xHTTP (see the man page for details).

If you also use the SSL wrapper feature in front of a Microsoft server you should probably also add HTTPSHeaders 1 "Front-End-Https: on"'

These changes are also required to access a Subversion server via Pound.

OTHER ISSUES

The following problems were reported by various people who use pound:

ACKNOWLEDGMENTS

Albert for investigating and writing the TCP_NODELAY code.

Luuk de Boer did some serious testing and debugging of the WebDAV code for Microsoft servers.

Dagobert Michelsen packages and makes available Solaris packages for various Pound versions.

David Couture found some nasty, lurking bugs, as well as contributing some serious testing on big hardware.

Frank Denis contributed a few excellent code patches and some good ideas.

Dmitriy Dvoinikov makes available a FreeBSD live-cd distribution which includes a Pound binary.

Abner G. Jacobsen did a lot of testing in a production environment and contributed some very nice ideas.

Akira Higuchi found a significant security issue in Pound and contributed the code to fix it.

Ken Lalonde contributed very useful remarks and suggestions, as well as correcting a few code errors.

Phil Lodwick contributed essential parts of the high-availability code and came up with some good ideas. In addition, did some serious testing under heavy loads.

Simon Matter packages and makes available RPMs for various Pound versions.

Jan-Piet Mens raised some interesting security points about the HTTPS implementation and brought the original idea for SSL header filtering.

Andreas Roedl for testing and some ideas about logging in root jails.

Shinji Tanaka contributed a patch for controlling logging to disk files.

Jim Washington contributed the code for WebDAV and tested it.

Maxime Yve discovered a nasty bug in the session tracking code and contributed the patch to fix it.

Paul Bukhovko makes available a translation in Belorussian.

Joe Gooch contributed many valuable suggestions and bug fixes.

Shin Sterneck contributed the packages for CRUX Linux.

Frank Schmirler contributed many useful patches and suggestions.

All the others who tested Pound and told me about their results.

Contact us

This field is for validation purposes and should be left unchanged.