Set a better default ciphers list if none was specified.
[pound.git] / README
1 POUND - REVERSE-PROXY AND LOAD-BALANCER
2
3     The Pound program is a reverse proxy, load balancer and
4     HTTPS front-end for Web server(s). Pound was developed
5     to enable distributing the load among several Web-servers
6     and to allow for a convenient SSL wrapper for those Web
7     servers that do not offer it natively. Pound is distributed
8     under the GPL - no warranty, it's free to use, copy and
9     give away.
10
11
12 WHAT POUND IS:
13
14     1.  a reverse-proxy: it passes requests from client
15         browsers to one or more back-end servers.
16
17     2.  a load balancer: it will distribute the requests from
18         the client browsers among several back-end servers,
19         while keeping session information.
20
21     3.  an SSL wrapper: Pound will decrypt HTTPS requests
22         from client browsers and pass them as plain HTTP
23         to the back-end servers.
24
25     4.  an HTTP/HTTPS sanitizer: Pound will verify requests
26         for correctness and accept only well-formed ones.
27
28     5.  a fail over-server: should a back-end server fail,
29         Pound will take note of the fact and stop passing
30         requests to it until it recovers.
31
32     6.  a request redirector: requests may be distributed
33         among servers according to the requested URL.
34
35     Pound is a very small program, easily audited for security
36     problems. It can run as setuid/setgid and/or in a chroot
37     jail. Pound does not access the hard-disk at all (except
38     for reading certificate file(s) on start, if required)
39     and should thus pose no security threat to any machine.
40
41
42 WHAT POUND IS NOT:
43
44     1.  Pound is not a Web server: by itself, Pound serves no
45         content - it contacts the back-end server(s) for that
46         purpose.
47
48     2.  Pound is not a Web accelerator: no caching is done -
49         every request is passed "as is" to a back-end server.
50
51
52 STATUS
53
54     As of release 1.0 Pound is declared to be production-quality code.
55
56     Quite a few people have reported using Pound successfully in production
57     environments. The largest volume reported to date is a site with an
58     average of about 30M requests per day, peaking at over 600 requests/sec.
59
60     Pound was successfully used in production with a variety of Web servers,
61     including Apache, IIS, Zope, WebLogic, Jakarta/Tomcat, iPlanet, etc. In
62     general Pound passes requests and responses back and forth unchanged,
63     so we have no reason to think that any web server would be incompatible.
64
65     Client browsers that were tested:
66
67     - IE 5.0/5.5 (Windows) HTTP/HTTPS
68
69     - Netscape 4.7 (Windows/Linux) HTTP/HTTPS
70
71     - Mozilla (Windows/Linux) HTTP/HTTPS
72
73     - Konqueror (Linux) HTTP/HTTPS
74
75     - Galleon (Linux) HTTP/HTTPS
76
77     - Opera (Linux/Windows) HTTP/HTTPS
78
79     - Lynx (Linux) HTTP
80
81     Given that Pound is in production and no problems were reported, we have
82     no reason to believe that other browsers would present a problem. A few
83     issues were observed with problematic SSL implementations, most notably
84     with Opera 6, but these should be OK in the present version.
85
86
87 INSTALLATION
88
89     Probably the easiest way to install Pound is to use a pre-compiled package
90     if you can find one. While Apsis offers no such packages, they are available
91     for quite a few systems (Suse, Debian and derivatives such as Ubuntu), as
92     well as some private packages:
93
94     - RPMs for RedHat are available at http://www.invoca.ch/pub/packages/pound/
95
96     - A nice FreeBSD live-CD distribution is available at http://www.targeted.org as
97     http://www.targeted.org/files/fbsd62_pound23.iso.gz, including a Pound binary.
98
99     Failing that you should install from sources:
100
101     1.  Pound was tested on Linux, Solaris and OpenBSD, but
102         it should work unchanged on just about any modern
103         Unix-like system. You will require at least OpenSSL and
104         libpthread. The PCRE package is strongly recommended.
105
106         Warning: as Pound is a multi-threaded program it requires
107         a version of OpenSSL with thread support. This is normally
108         the case on Linux and Solaris (for example) but not on *BSD.
109         If your system has the wrong library please download, compile
110         and install OpenSSL (from http://www.openssl.org).
111
112         If the PCRE package is available Pound will link against it.
113         This will provide a significant performance boost.
114
115     2.  Download the current version of Pound-current file and unpack
116         it. The archive is signed.
117         My signature is available at http://www.apsis.ch/pound/roseg.asc.
118         Alternately see below for stable versions.
119
120         Unpack. Do the usual thing:
121
122             ./configure
123
124     3.  The following options are available for the configure script:
125
126         --with-ssl=ssl_dir -- OpenSSL home directory (default: system defined).
127
128         --disable-super -- disable supervisor process (default: enabled)
129
130         --with-t_rsa=nnn   -- timeout of the RSA ephemeral keys regeneration
131         (default: 1800 seconds).
132
133         --with-owner=owner -- name of installed binaries owner (default is
134         system-dependent).
135
136         --with-group=group -- name of installed binaries group (default is
137         system-dependent).
138
139     4.  Check that the resulting Makefile is correct and possibly
140         adjust flags as needed on your system. Compile:
141
142             make
143
144     5.  If it works, you may want to do some testing before installing.
145
146     6.  Install the executable somewhere (it's likely that
147         /usr/local/sbin would make a good choice), as well
148         as the manual page (pound.8 -> /usr/local/man/man8).
149         The supplied Makefile will do it for you.
150
151     7.  Make sure Pound gets started on boot. Read the man
152         page for available options and examples.
153
154
155 COPYRIGHT
156
157     Pound is copyrighted by Apsis GmbH and is distributed under
158     the terms of the GNU Public License with the additional
159     exemption that compiling, linking, and/or using OpenSSL is
160     allowed. Basically, this means that you can use it free of
161     charge, copy it, distribute it (provided the copyright is
162     maintained and the full package is distributed), modify it,
163     or line a bird-cage with it.
164
165     We would be happy to hear from you if you use it and
166     suggestions and improvements are gladly accepted.
167
168
169 CONTACT
170
171     Robert Segall, roseg@apsis.ch
172
173     Apsis GmbH, http://www.apsis.ch
174
175     P O Box
176
177     CH-8707 Uetikon am See
178
179     Switzerland
180
181     +41-44-920 4904
182
183
184 MAILING LIST
185
186     Pound has its own mailing list now: please send a message with
187     the subject "subscribe" to pound@apsis.ch in order to
188     subscribe. You will receive confirmation and instructions in
189     the reply.
190
191     All messages are available and indexed (searcheable) in the
192     archive http://www.apsis.ch/pound/pound_list.
193
194     The mailing list is the primary support forum for Pound - please
195     post there any questions you may have. The developpers' address is
196     given here for information purposes only.
197
198
199
200 ZOPE
201
202     A special note for Zope users: the original intent on
203     developing Pound was to allow distributing the load
204     among several Zope servers running on top of ZEO. This
205     it does.
206
207     A special problem arises when you try using Pound as an
208     SSL wrapper: Zope assumes that the requests are made via
209     HTTP and insists on prepending 'http://' to the (correct)
210     address in the replies, including in the <base> tag and
211     the absolute URLs it generates (for images for example).
212     This is clearly an undesirable behavior.
213
214     For older Zope versions (prior to 2.7): a modified z2.py (as
215     well as a patch) is included in the distribution. The main
216     difference is that this z2.py allows starting an additional
217     HTTP server via the -y flag that sets the environment
218     HTTPS variable - thus correcting the problem. That means
219     that in order to use Pound as an SSL wrapper you need to:
220
221     - start Zope (modify the 'start' file) as:
222
223         python -X -w 8080 -y 8443 ...
224
225     For Zope 2.7 or later the same effect can be achieved via suitable
226     modifications to zope.conf.
227
228
229
230 VIRTUAL HOSTS (IN GENERAL)
231
232     Some people asked about the possibility of redirecting requests to back-ends
233     as per some virtual hosts definition. While I believe this is not Pound's
234     job, it can be done. As of version 0.10, Pound supports filtering requests
235     based not only on the request URL, but also on the presence or absence of
236     certain headers.
237
238     Let's assume that you have internal server 192.168.0.10 that is supposed to
239     serve the needs of virtual host www.server0.com and 192.168.0.11 that serves
240     www.server1.com.  You want Pound to listen on address 1.2.3.4 and separate
241     the requests to each host.  The config file would look something like this:
242
243         ListenHTTP
244             Address 1.2.3.4
245             Port    80
246
247             Service
248                 HeadRequire "Host: .*www.server0.com.*"
249
250                 BackEnd
251                     Address 192.168.0.10
252                     Port    80
253                 End
254             End
255
256             Service
257                 HeadRequire "Host: .*www.server1.com.*"
258
259                 BackEnd
260                     Address 192.168.0.11
261                     Port    80
262                 End
263             End
264         End
265
266     (add whatever else is necessary) or, if you want even safer filtering:
267
268         ListenHTTP
269             Address 1.2.3.4
270             Port    80
271
272             Service
273                 HeadRequire "Host: .*www.server0.com.*"
274                 HeadDeny    "Host: .*www.server1.com.*"
275
276                 BackEnd
277                     Address 192.168.0.10
278                     Port    80
279                 End
280             End
281
282             Service
283                 HeadRequire "Host: .*www.server1.com.*"
284                 HeadDeny    "Host: .*www.server0.com.*"
285
286                 BackEnd
287                     Address 192.168.0.11
288                     Port    80
289                 End
290             End
291         End
292
293     This is NOT recommended (I personally believe that virtual hosts should be
294     implemented in the back-end servers - putting this in a proxy
295     is a major security kludge) but it works.
296
297
298
299 VIRTUAL HOSTS AND HTTPS
300
301     Quite often we get inquiries about Pound's ability to do virtual hosting
302     with HTTPS. In order to lay this matter to rest, let me say:
303
304         HTTPS does not allow virtual hosting!
305
306     This is not a limitation of Pound, but of HTTPS - no Web server or proxy
307     are able to do it due to the nature of the beast.
308
309     In order to see why this is the case we need to look at the way HTTPS works.
310     Basically there are three stages in any HTTPS connection:
311
312     1.  Connection negotiation - the client (your browser) and the server (Web
313         server or proxy) negotiate the basic parameters: ciphers to use, session
314         key, etc.
315
316     2.  Connection authentication: at the very least the server presents the
317         client with a certificate that says "I am server www.encrypted.com - and
318         certificate.authority.org will verify that". The client may also present
319         a certificate of its own at this stage.
320
321     3.  Request/response cycle: normal HTTP is sent (through the encrypted
322         channel) back and forth.
323
324     The vital point to notice here is that connection authentication takes place
325     BEFORE any request was issued.
326
327     On the other hand, the way virtual hosting works is for the client to
328     specify in the request to which server it would like to talk. This is
329     accomplished via a Host header:
330
331         GET /index.html HTTP/1.1
332         Host: http://www.virthost.com
333
334     Combining the two we get to an impasse: on connection setup the server will
335     reply with the certificate for "www.realhost.com", but the request is really
336     for "www.virthost.com" - and most browsers will scream blue murder (as well
337     they should) if the two do not match.
338
339     There is a new twist on this however: some of the newer browsers will accept
340     so-called "wild-card certificates". This is a specially crafted certificate
341     that is not issued to a host, but rather to a domain. The result is that
342     on setting-up a new SSL connection, the server replies not with "I am
343     www.encrypted.com", but with "I am *.encrypted.com". If the browser is
344     capable of processing this type of certificate then the connection is
345     set up and normal HTTPS (with www.encrypted.com or special.encrypted.com or
346     even some.other.server.encrypted.com or whatever other name matches) proceeds
347     as usual. Pound supports these certificates and you can use virtual hosts in
348     the normal way.
349
350     Update June 2010: starting with the 2.6 series, Pound has SNI support, if your
351     OpenSSL version supports it. Basically you supply Pound with several certificates,
352     one for each virtual host (wild card certificates - as described above - are
353     allowed). On connecting the client signals to which server it wants to talk,
354     and Pound searches among its certificates which would fit. Not all versions
355     of OpenSSL and not all clients support this mode, but if available it allows
356     for virtual hosts over HTTPS.
357
358     An additional option is to use a semi-official TLS extension, the so called
359     alternate subject name. If your version of OpenSSL supports it you may specify
360     in one certificate several alternate server names. This requires support for a
361     special TLS feature, and nor all clients accept it.
362
363
364
365 VIRTUAL HOSTS IN ZOPE
366
367     For reasons I can't quite grasp, it seems that a lot of Zope
368     users are convinced that virtual hosts are only possible through
369     the Apache/VHM combination and that it requires some kind of
370     magic incantation at midnight in order to work (I won't even
371     start on the virgin sacrifices).
372
373     The simple fact is that VHM and the Apache VirtualHost directives
374     (as well as various tricks through mod_rewrite and mod_proxy) are
375     (almost) mutually exclusive: they perform exactly the same
376     functions and, leaving aside the logging issues, are used
377     independently of each other.  Let me repeat that: you may use the
378     VHM without Apache - just click on the VHM mappings tab and add
379     whatever virtual host you wish. From this moment on any request
380     to that host will be mapped back and forth by Zope to the required
381     URL. This works weather you access Zope directly or via any number
382     of proxies on the way, Pound included.
383
384     To test: add a new host name to your /etc/hosts file, making it an
385     alias for localhost - something like::
386
387         127.0.0.1 localhost www.testhost.mine
388
389     Add a mapping in VHM from www.testhost.mine to some Zope folder
390     (Examples is already there). Point your browser to http://localhost
391     and you get the normal Zope start page; point it to
392     http://www.testhost.mine and you'll see the Examples starting page.
393     All requests are mapped correctly, and the URLs in the pages (such
394     as base or absoluteURL) are translated correctly in the response.
395
396
397 SESSIONS
398
399     Pound has the ability to keep track of sessions between a client
400     browser and a back-end server. Unfortunately, HTTP is defined as
401     a stateless protocol, which complicates matters: many schemes have
402     been invented to allow keeping track of sessions, none of which works
403     perfectly. Even worse, sessions are critical in order to allow
404     web-based applications to function correctly - it is vital that once
405     a session is established all subsequent requests from the same browser
406     be directed to the same back-end server.
407
408     Six possible ways of detecting a session have been implemented in
409     Pound (hopefully the most useful ones): by client address, by Basic
410     authentication (user id/password), by URL parameter, by cookie, by
411     HTTP parameter and by header value.
412
413     - by client address: in this scheme Pound directs all requests from
414       the same client IP address to the same back-end server. Put the
415       lines
416       
417       Session
418         Type    IP
419         TTL     300
420       End
421       
422       in the configuration file to achieve this effect. The value indicates
423       what period of inactivity is allowed before the session is discarded.
424
425     - by Basic Authentication: in this scheme Pound directs all requests from
426       the same user (as identified in the Basic Authentication header) to the
427       same back-end server. Put the lines
428
429       Session
430         Type    Basic
431         TTL     300
432       End
433       
434       in configuration file to achieve this effect. The value indicates what
435       period of inactivity is allowed before the session is discarded.
436
437       WARNING: given the constraints of the HTTP protocol it may very well be
438       that the authenticated request will go to a different back-end server than
439       the one originally requesting it. Make sure all your servers support
440       the same authentication scheme!
441
442     - by URL parameter: quite often session information is passed through URL
443       parameters (the browser is pointed to something like http://xxx?id=123).
444       Put the lines
445
446       Session
447         Type    URL
448         ID      "id"
449         TTL     300
450       End
451
452       to support this scheme and the sessions will be tracked based on the value
453       of the "id" parameter.
454
455     - by cookie value: applications that use this method pass a certain cookie
456       back and forth. Add the lines
457       
458       Session
459         Type    Cookie
460         ID      "sess"
461         TTL     300
462       End
463
464       to your configuration file - the sessions will be tracked by the value of
465       the "sess" cookie.
466
467     - by HTTP parameter value: applications that use this method pass an HTTP
468       parameter (http://x.y/z;parameter) back and forth. Add the lines
469       
470       Session
471         Type    PARM
472         TTL     300
473       End
474
475       to your configuration file - the sessions will be tracked by the value of
476       the parameter.
477
478     - by header value: applications that use this method pass a certain header
479       back and forth. Add the lines
480       
481       Session
482         Type    Header
483         ID      "X-sess"
484         TTL     300
485       End
486
487       to your configuration file - the sessions will be tracked by the value of
488       the "X-sess" header.
489
490     Please note the following restrictions on session tracking:
491
492     - session tracking is always associated with a certain Service. Thus each
493       group may have other methods and parameters.
494
495     - there is no default session: if you have not defined any sessions no
496       session tracking will be done.
497
498     - only one session definition is allowed per Service. If your application
499       has alternative methods for sessions you will have to define a separate
500       Service for each method.
501
502     A note on cookie injection: some applications have no session-tracking mechanism at
503     all but would still like to have the client always directed to the same back-end
504     time after time. Some reverse proxies use a mechanism called "cookie injection" in
505     order to achieve this: a cookie is added to the back-end responses and tracked by the
506     reverse proxy.
507
508     Pound was designed to be as transparent as possible, and this mechanism is not
509     supported. If you really need this sort of persistent mapping use the client address
510     session mechanism (Session Type IP), which achieves the same result without
511     changing the contents in any way.
512
513
514 REQUEST LOGGING
515
516     As a general rule, Pound passes all headers as they arrive from the client
517     browser to the back-end server(s). There are two exceptions to this rule:
518     Pound may add information about the SSL client certificate (as described
519     below), and it will add an X-Forwarded-For header. The general format is:
520
521         X-Forwarded-for: client-IP-address
522
523     The back-end server(s) may use this extra information in order to create
524     their log-files with the real client address (otherwise all requests will
525     appear to originate from Pound itself, which is rather useless).
526
527     In addition, Pound logs requests and replies to the system log. This is
528     controlled by the LogLevel configuration variable (0 - no logging,
529     1 - normal log, 2 - full log, 3 - Apache combined log format, 4 - Apache
530     combined log format without virtual host).
531
532     By default the messages go to the LOG_DAEMON facility, but you can change
533     this in the configuration file. If you don't want to, you can just do a:
534
535         fgrep pound /var/log/messages
536
537     to get all the messages generated by Pound.
538
539
540 HTTPS CERTIFICATES
541
542     If a client browser connects via HTTPS and if it presents a
543     certificate and if HTTPSHeaders is set, Pound will obtain the
544     certificate data and add the following HTTP headers to the
545     request it makes to the server:
546
547     - X-SSL-Subject: information about the certificate owner
548
549     - X-SSL-Issuer: information about the certificate issuer (CA)
550
551     - X-SSL-notBefore: begin validity date for the certificate
552
553     - X-SSL-notAfter: end validity date for the certificate
554
555     - X-SSL-serial: certificate serial number (in decimal)
556
557     - X-SSL-cipher: the cipher currently in use
558
559     - X-SSL-certificate: the full client certificate (multi-line)
560
561     It is the application's responsibility to actually use these
562     headers - Pound just passes this information without checking
563     it in any way (except for signature and encryption correctness).
564
565     Please note that this mechanism allows forgeries: a client may
566     (maliciously) send these headers to Pound in order to masquerade
567     as an SSL client with a specific certificate. If this is a problem
568     for your application make sure to deny these requests. Add:
569
570         HeadDeny "X-SSL-Subject:.*"
571         HeadDeny "X-SSL-Issuer:.*"
572         HeadDeny "X-SSL-notBefore:.*"
573         HeadDeny "X-SSL-notAfter:.*"
574         HeadDeny "X-SSL-serial:.*"
575         HeadDeny "X-SSL-cipher:.*"
576
577     within the Service(s).
578
579
580 THREADS AND LIMITS
581
582     A few people ran into problems when installing Pound because of the
583     various threading models and how they interact with system-imposed
584     limits. Please keep in mind the following requirements:
585
586     - on most System V derived Unices (of which Linux up to 2.4 is one),
587       a thread is a process. This means that when doing a 'ps' you will see
588       as many processes with the name 'pound' as there are active threads.
589       Each such process uses only two file descriptors, but the system needs
590       to support the required number of processes, both in total and per
591       user (possibly also per process group). In bash, this is 'ulimit -u',
592       in csh this is 'limit maxproc'.
593
594     - on BSD style systems all threads run in the same process space. Do
595       a ps and you see a single 'pound' process. The process needs two
596       file descriptors per active request (bash: 'ulimit -n', csh
597       'limit maxfiles'/'limit openfiles').
598
599     - on most systems the thread library comes with a built-in limit on the
600       maximal number of concurrent threads allowed - on older systems it usually
601       is 1024, on newer systems quite a bit higher. In very
602       rare cases (very high load and long response times) you may run into
603       this limitation - the symptom is log messages saying "can't create
604       thread". Your only solution is to recompile the system threads library
605       (and possibly the kernel itself) with a higher limit.
606
607     Please note that your kernel needs to be configured to support the
608     required resources - the above are just the shell commands.
609
610 SIMILAR SYSTEMS
611
612     Quite a few people asked "What is wrong with Apache/Squid/
613     stunnel/your_favorite? Do we really need another proxy
614     system?". The simple answer is that there is nothing wrong -
615     they are all excellent systems that do their jobs very well.
616     The reasoning behind Pound is however slightly different:
617
618     - In my experience, a load-balancer may easily become a
619       bottle-neck in itself. If you have a heavily loaded site,
620       there are few things more depressing than seeing your
621       "load-balancer" slow down the entire network. This means that
622       the load-balancer should be kept as light-weight as possible.
623
624     - Security: auditing a large system for security issues is a
625       major undertaking for anybody (ask Bill Gates about it). This
626       implies that in order to avoid introducing new vulnerabilities
627       into a system (after all, your installation is only as secure
628       as its weakest component) the proxy/load-balancer should be
629       kept as small as possible.
630
631     - Protection: I assume Pound will be the only component exposed
632       to the Internet - your back-end servers will run in a protected
633       network behind it. This means that Pound should filter requests
634       and make sure only valid, correctly formed ones are passed to the
635       back-end servers, thus protecting them from malicious clients.
636
637     Taking these criteria into consideration, it is easy to see why
638     the other systems mentioned above do not fit:
639
640     - Apache (with mod_proxy and mod_backhand): great system, but very
641       large. Imposes a significant load on the system, complex set-up
642       procedure (and it is so easy to get it wrong: check how many Apache
643       servers allow proxying from and to external hosts). While Apache
644       has proven remarkably exploit free, I wouldn't wish to go into a
645       security audit for the tens of thousands of lines of code involved,
646       not to mention all the additional modules.
647
648     - Squid: great caching proxy, but even should load-balancing
649       features become available in the future, do you really need
650       caching on the load-balancer? After all, Pound can easily run on a
651       disk-less system, whereas with Squid you'd better prepare a high
652       throughput RAID. Squid is still perfectly usable as a caching
653       proxy between Pound and the actual Web server, should it lack
654       its own cache (which Zope happily has).
655
656     - stunnel: probably comes closest to my understanding of software
657       design (does one job only and does it very well). However, it
658       lacks the load balancing and HTTP filtering features that I
659       considered necessary. Using stunnel in front of Pound (for HTTPS)
660       would have made sense, except that integrating HTTPS into Pound
661       proved to be so simple that it was not worth the trouble.
662
663     - your favourite system: let me know how it looks in light of the
664       above criteria - I am always interested in new ideas.
665
666
667 DEDICATED SERVERS
668
669     Some people asked about the possibility of dedicating specific
670     back-end servers to some clients - in other words, if a request
671     originates from a certain IP address or group of addresses then
672     it should be sent to a specific group of back-end servers.
673
674     Given the ease with which IP addresses can be forged I am personally
675     doubtful of the utility of such a feature. Even should you think it
676     desirable, it is probably best implemented via the packet filter,
677     rather than a proxy server. Assuming that requests from x.com are
678     to go to s1.local, requests from y.com to s2.local and everything
679     else to s3.local and s4.local, here is how to do it:
680
681     - make sure your firewall blocks requests to port 8080, 8081 and 8082
682
683     - configure Pound as follows:
684
685         ListenHTTP
686             Address 127.0.0.1
687             Port    8080
688
689             Service
690                 BackEnd
691                     Address s1.local
692                     Port    80
693                 End
694             End
695         End
696
697         ListenHTTP
698             Address 127.0.0.1
699             Port    8081
700
701             Service
702                 BackEnd
703                     Address s2.local
704                     Port    80
705                 End
706             End
707         End
708
709         ListenHTTP
710             Address 127.0.0.1
711             Port    8082
712
713             Service
714                 BackEnd
715                     Address s3.local
716                     Port    80
717                 End
718                 BackEnd
719                     Address s4.local
720                     Port    80
721                 End
722             End
723         End
724
725     - have your packet filter redirect requests to the right local ports
726       based on the origin address. In OpenBSD pf syntax this would be
727       something like:
728
729         rdr on rl0 from x.com to myhost.com port 80 -> localhost port 8080
730         rdr on rl0 from y.com to myhost.com port 80 -> localhost port 8081
731         rdr on rl0 from any to myhost.com port 80 -> localhost port 8082
732
733       or in Linux iptables::
734
735         iptables -t nat -A PREROUTING -p tcp -s x.com --dport 80 -i eth0 \
736             -j DNAT --to 127.0.0.1:8080
737         iptables -t nat -A PREROUTING -p tcp -s y.com --dport 80 -i eth0 \
738             -j DNAT --to 127.0.0.1:8081
739         iptables -t nat -A PREROUTING -p tcp --dport 80 -i eth0 -j DNAT \
740             --to 127.0.0.1:8082
741
742     This would give you the desired effect and probably better
743     performance than a purely proxy-based solution (though the
744     performance improvement is debatable, at least on Linux).
745
746
747 WebDAV
748
749     As of version 1.0 Pound supports the full WebDAV command-set. In
750     fact, it has been tested and is known to (almost) work with the
751     Microsoft Outlook Web Gateway, which is quite remarkable given that
752     Microsoft's own proxy does not.
753
754     Regrettably, Microsoft adherence to standards leaves something to be
755     desired: they decided to add some characters to their URLs - thus
756     breaking a whole set of RFC's.
757
758     Rather then change Pound to accept these characters (which could create
759     some serious issues with security on other systems) we have made this
760     behaviour dependent on a configuration switch: xHTTP (see the man page
761     for details).
762
763     If you also use the SSL wrapper feature in front of a Microsoft server
764     you should probably also add 'AddHeader "Front-End-Https: on"'.
765
766     These changes are also required to access a Subversion server via
767     Pound.
768
769
770 OTHER ISSUES
771
772     The following problems were reported by various people who use pound:
773
774     - delays in loading pages when the client browser is IE 5.5 (possibly
775       limited to W2K/XP). It seems that IE opens exactly 4 connections (sockets)
776       to the server and keeps them open until some time-out or until the server
777       closes the connection. This works fine, unless you redirect IE to another
778       server - given that all 4 sockets are used IE waits for a while before
779       the redirect is actually performed.
780
781       Solution: use the directive "Client 1" to ensure that Pound closes
782       sockets very early, thus freeing the necessary resources. Experiment with
783       the time-out - as it may cause problems with slow connections.
784
785     - Pound fails to start; HTTPS is enabled and the message "can't read
786       private key from file xxx" appears in the log.
787
788       Solution: make sure that the certificate file includes:
789
790       - (optional) a chain of certificates from a known certificate authority to
791         your server certificate
792
793       - the server certificate
794
795       - the private key; the key may NOT be password-protected
796
797       The file should be in PEM format. The OpenSSL command to generate a
798       self-signed certificate in the correct format would be something like::
799
800         openssl req -x509 -newkey rsa:1024 -keyout test.pem -out test.pem \
801             -days 365 -nodes
802
803       Note the '-nodes' flag - it's important!
804
805     - Pound fails to operate correctly with SSL when RootJail is specified.
806       Solution: OpenSSL requires access to /dev/urandom, so make sure such a
807       device is accessible from the root jail directory. Thus if your root
808       jail is something like /var/pound:
809
810         mkdir /var/pound/dev
811         mknod /var/pound/dev/urandom c 1 9
812
813       or whatever major/minor number are appropriate for your system.
814
815     - In chroot mode logging may stop functioning.
816       Solution: make sure /dev and the root jail are on the same filesystem
817       and create a hard link in the root jail to /dev/log:
818
819         mkdir /chroot/jail/dev
820         ln /dev/log /chroot/jail/dev/log
821
822       Alternately you can have syslog (or syslog-ng) listen on another
823       socket - see the man page for details.
824
825     - In chroot mode name resolution (and especially redirects) may stop
826       functioning.  Solution: make sure your resolver works correctly in the
827       jail. You probably need copies of /etc/resolv.conf and (at least part)
828       of /etc/hosts. Depending on your system additional files may be required
829       check your resolver man page for details. Should name resolution fail the
830       translation of host names to IP addresses would fail, thereby defeating
831       the mechanism Pound uses to identify when should a Redirect be rewritten.
832
833     - IE 5.x fails to work (correctly or at all) with Pound in HTTPS mode.
834       Solution: define the supported OpenSSL ciphers for IE compatibility (this
835       is really a work-around for a known IE bug):
836
837       Ciphers "ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL"
838
839       (Thanks to Andi Roedl for the tip).
840
841     - Linux-specific: some people use various redundant Pound solutions for
842       Linux which require Pound instances on separate machines to bind to the
843       same address. The default configuration of Linux does not allow a
844       program to bind() to non-local addresses, which may cause a problem.
845       Solution: add
846       
847         echo 1 > /proc/sys/net/ipv4/ip_nonlocal_bind
848
849       in your start-up script, or just set
850
851         net.ipv4.ip_nonlocal_bind = 1
852
853       in /etc/sysctl.conf (if you have one).
854
855       (Thanks to RUne Saetre for the suggestion).
856
857
858 ACKNOWLEDGMENTS
859
860     Albert (of Alacra) for investigating and writing the TCP_NODELAY code.
861
862     Luuk de Boer did some serious testing and debugging of the WebDAV
863     code for Microsoft servers.
864
865     Alession Cervellin packages and makes available Solaris packages for
866     various Pound versions.
867
868     David Couture found some nasty, lurking bugs, as well as contributing
869     some serious testing on big hardware.
870
871     Frank Denis contributed a few excellent code patches and some good ideas.
872
873     Dmitriy Dvoinikov makes available a live-CD FreeBSD distribution that
874     includes a Pound binary.
875
876     Abner G. Jacobsen did a lot of testing in a production environment
877     and contributed some very nice ideas.
878
879     Akira Higuchi found a significant security issue in Pound and contributed
880     the code to fix it.
881
882     Ken Lalonde contributed very useful remarks and suggestions, as well as
883     correcting a few code errors.
884
885     Phil Lodwick contributed essential parts of the high-availability code and
886     came up with some good ideas. In addition, did some serious testing under
887     heavy loads.
888
889     Simon Matter packages and makes available RPMs for various Pound versions.
890
891     Jan-Piet Mens raised some interesting security points about the HTTPS
892     implementation and brought the original idea for SSL header filtering.
893
894     Andreas Roedl for testing and some ideas about logging in root jails.
895
896     Gurkan Sengun tested Pound on Solaris, contributed the Solaris cc flags
897     and makes a Solaris pre-compiled version available on his Web-site
898     (www.linuks.mine.nu)
899
900     Shinji Tanaka contributed a patch for controlling logging to disk files.
901     This is available at http://www.hatena-inc.co.jp/~stanaka/pound/
902
903     Jim Washington contributed the code for WebDAV and tested it.
904
905     Maxime Yve discovered a nasty bug in the session tracking code and
906     contributed the patch to fix it.
907
908     All the others who tested Pound and told me about their results.