Set a better default ciphers list if none was specified.
[pound.git] / FAQ
1 FREQUENTLY ASKED QUESTIONS
2
3 1. General
4 ==========
5
6 1.1 Will Pound run my Web application?
7
8     No. Pound is a proxy, not a Web server - it does not deliver content by
9     itself. It is just the middle-man between a client and a server.
10
11 1.2 Will Pound make my server go faster?
12
13     No. Pound is just a proxy - no caching of any kind takes place. Pound
14     IS able to distribute requests between several back-end servers, thus
15     allowing for faster overall response times, but it won't speed-up a
16     single Web sever.
17
18 1.3 Will Pound make my server more secure?
19
20     Probably yes. Pound has its own checks on the validity of HTTP requests
21     and often catches malicious requests that are used to attack Web servers.
22
23 1.4 Can I use Pound to change/rewrite/redirect requests?
24
25     No. Pound tries to be as transparent as possible - ideally a client
26     should not be aware that there is anything between itself and the actual
27     Web server. A limited form of redirect is available - see the man page.
28
29 1.5 Can I use Pound to deny certain requests?
30
31     Yes. Pound has a rather good mechanism for classifying requests and it
32     can deny/reject certain requests based on URL and/or header content.
33
34
35 2. Configuration, Compilation and Installation
36 ==============================================
37
38 2.1 I try to compile and it fails on "needs OpenSSL with thread support"
39
40     Pound is a multi-threaded program and it needs an OpenSSL library
41     compiled with thread support (optional in the OpenSSL configuration and
42     absent in some default installations, such as *BSD). If your default
43     library does not support threads you must install a thread-enabled
44     version.
45
46 2.2 Pound compiles correctly but crashes on *BSD
47
48     On some of the newer versions of *BSD (FreeBSD 5.x, OpenBSD 3.x) the
49     Pound autoconf may not correctly recognize the threading library. Add
50     manually to the generated Makefile the option -DNEED_STACK in the
51     CFLAGS.
52
53 2.3 I want to run Pound with daemon-tools but it goes to background
54
55     You need to configure Pound for non-daemon operations: add "Daemon 0"
56     to the config file.
57
58 2.4 Pound runs OK but some normal requests are rejected with "bad URL"
59
60     Pound checks the requested URLs quite thoroughly and rejects malformed
61     or illegal URLs - or at least illegal according to the RFCs. See the
62     man page for details.
63
64 2.5 Pound runs OK but I get a "pthread_create" error message
65
66     You may be hitting the system limit on the number of processes. On
67     systems that implement threads as processes (as Linux does) you should
68     make sure that the Pound process has permission to start a sufficient
69     number of processes.
70
71     In some rare cases you may be running into the system limit on the
72     number of threads. Check your system details for the value of
73     PTHREAD_THREADS_MAX. If needed you must recompile the threads library
74     with a higher value.
75
76 2.6 What resources does Pound need/use?
77
78     That depends very much on your system. On some systems, such as Linux
79     and System V (AIX, HP-UX, etc), threads are implemented as processes,
80     which means you must allow enough processes to run. On other systems,
81     such as *BSD, where threads are implemented in user space (in-process),
82     you should make sure that Pound can use sufficient memory for all the
83     threads and that the process is allowed to use enough file descriptors
84     (2 per active connection). Finally, on systems that implement threads
85     natively, such as Solaris, you need to make sure that enough threads
86     and open file descriptors are allowed.
87
88 2.7 Is NPTL supported?
89
90     Theoretically Pound will work with any POSIX-compliant threads package.
91     In practice some of the newer NPTL implementations still have some
92     bugs. At least on Linux running Pound with LD_ASSUME_KERNEL=2.4.19
93     may be helpful.
94
95
96 3. Virtual Hosts
97 ================
98
99 3.1 How do I redirect specific virtual hosts to specific back-ends?
100
101     Make the virtual host mandatory in the UrlGroup. For example, to have
102     all requests to www.a.com go to 192.168.0.10 and all requests for
103     www.b.com go to 192.168.0.20, define
104
105         Service
106             HeadRequire "Host:.*www.a.com.*"
107             BackEnd
108                 Address 192.168.0.10
109                 Port    80
110             End
111         End
112
113         Service
114             HeadRequire "Host:.*www.b.com.*"
115             BackEnd
116                 Address 192.168.0.20
117                 Port    80
118             End
119         End
120
121     in your config file.
122
123 3.2 How do I redirect requests to specific back-ends based on the client
124     address?
125
126     You can do it easier via the packet filter you use. If you insist on
127     having Pound do it use a combination of port redirection and separate
128     instances of Pound for each port. For example, assume you want intranet
129     clients (on 192.168.100.0/24) to use the server at 192.168.1.10 and
130     external clients go to 192.168.1.20. Do the following:
131
132         - redirect requests from 192.168.100.0/24 to port 8080
133
134             pf: rdr on rl0 from 192.168.100.0/24 to 192.168.100.1 port 80 \
135                 -> localhost port 8080
136
137             netfilter: iptables -t nat -A PREROUTING -p tcp \
138                 -s 192.168.100.0/24 --dport 80 -i eth0 -j DNAT \
139                 --to localhost:8080
140
141         - redirect requests from anywhere else to port 8081
142
143             pf: rdr on rl0 from any to 192.168.100.1 port 80 \
144                 -> localhost port 8081
145
146             netfilter: iptables -t nat -A PREROUTING -p tcp \
147                 --dport 80 -i eth0 -j DNAT --to localhost:8081
148
149         - have a Pound listener on port 8080 and sending the
150           requests to 192.168.1.10
151
152         - have a Pound listener on port 8081 and sending the
153           requests to 192.168.1.20
154
155 3.3 What happens when my server replies with a redirect?
156
157     Depending on configuration, Pound can watch for redirect replies from back-ends
158     and change them to the correct address. In order for this to happen the
159     following conditions must be met:
160
161     - Pound has "Check30x 1"
162     - the back-end replies with a redirect. The address of that URL resolves to
163       the same address as the one Pound is listening on or the address of the
164       back-end itself.
165
166     This feature is commonly used when Pound serves as a HTTPS wrapper,
167     as the backend redirect to "Location: http://x.y.com" is rewritten as
168     "Location: https://x.y.com".
169
170
171 4. HTTPS
172 ========
173
174 4.1 Can I have Pound force HTTPS connections to certain URLs/back-ends?
175
176     Yes - define a Service with a Redirect back-end.
177
178 4.2 How can I do virtual hosting with HTTPS?
179
180     The simple answer is that neither you, nor anybody else can, due to a
181     limitation of the HTTPS protocol. In its simplest form an HTTPS (SSL)
182     connection goes through the following stages:
183
184     - negotiation: the client contacts the server, receives a certificate
185       from it, and negotiates the protocol details (cipher parameters, etc).
186
187     - authentication: the client checks that the certificate received matches
188       the server it wanted and validates that the certificate is correct as
189       attested by some certificate authority.
190
191     - request/response: normal HTTP, encrypted in transit.
192
193     As you can see the certificate is sent before any request was received.
194     Unfortunately, the first request specifies the virtual host that the
195     client would like to talk to - and it may not match the server name in
196     the certificate.
197
198 4.3 Pound does not start with message "can't read private key"
199
200     The file you specify in the ListenHTTPS directive must contain both the
201     server certificate and the private key to it in PEM format. See the man
202     page for SSL_CTX_use_PrivateKey_file(3) for details.
203
204 4.4 How can a back-end know that the connection is via HTTPS?
205
206     Pound can add a header for incoming requests indicating that they were
207     received via HTTPS. See the details on AddHeader in the man page.
208
209 4.5 HTTPS connections fail when Pound runs chrooted
210
211     The OpenSSL library requires access to /dev/urandom for its random seed.
212     The normal device is not accessible in a jail root. You should add a
213     link to the device to make it accessible. On Linux this would be:
214
215         mknod /var/pound/dev/urandom c 1 9
216
217     assuming that /var/pound is the root jail.
218
219 4.6 How can I force a back-end to generate the correct URL with HTTPS
220
221     There is no simple answer to this question - each server and application
222     have their own way of doing things. If your server does not use absolute
223     paths then all is well - things will run out of the box. However if some
224     frames, images, links or a base tag are generated with an absolute path
225     you must find a way to force the generation with https://.
226
227 4.7 How can I find out about the client certificate in my application?
228
229     For requests via HTTPS connections Pound can add the details of the
230     client certificate as headers to each and every request it passes to
231     the back-end. See the details on HTTPSHeaders in the man page.
232
233 4.8 Can Pound use my crypto accelerator hardware?
234
235     Pound supports the OpenSSL engine architecture. If your crypto card is
236     supported by OpenSSL then it is supported by Pound. See the SSLEngine
237     directive in the man page.
238
239 4.9 Can Pound use HTTPS back-end servers?
240
241     Yes, but that is not always a very good idea. Such a setup would essentially
242     make Pound into a "man-in-the-middle" program. Even worse, the certificates
243     on the back-end would become meaningless - they are seen only by Pound.
244
245
246 5. Session tracking
247 ===================
248
249 5.1 Can I have session tracking based on URL and/or Cookie?
250
251     Pound can track sessions based on client IP address, a cookie, an URL
252     parameter or BasicAuthentication. These options are mutually exclusive -
253     only one of them can be used per UrlGroup.
254
255 5.2 When does a session expire?
256
257     A session is kept for the specified number of seconds. If during this
258     time no new request was received the session is discarded.
259
260 5.3 Does Pound create/track its own sessions?
261
262     No. Pound does not add anything to the requests or the responses - it
263     uses the tokens generated by the back-end servers exclusively.
264
265
266 6. Logging
267 ==========
268
269 6.1 Can I use Webalizer on Pound log files?
270
271     Yes. If you use LogLevel 3 or 4 Pound uses one of the standard log
272     formats that are recognized by applications such as Webalizer. You will
273     have to remove the time-stamp generated by the syslog - see cut(1) for
274     details.
275
276 6.2 How do I log the original client address in the back-end log?
277
278     Pound adds the X-Forwarded-for header with the original client address
279     to every request. Use it for your logs on the back-end servers.
280
281 6.3 How can I separate the Pound log from other syslog messages?
282
283     If you use the syslog facility you can configure it to send the pound
284     messages to a separate file. You may want to separate by severity as
285     well - normal log messages use LOG_INFO, everything else is not request
286     information. See syslogd(8) for details on how to configure it.
287
288 6.4 How can I separate error messages from normal log messages?
289
290     If you use syslog: normal requests are logged at LOG_INFO, everything
291     else is higher.
292
293     If you run without syslog: normal request logging to stdout, everything
294     else to stderr.
295
296 6.5 Why does Pound not log anything when chrooted?
297
298     On some systems you need access to /dev/log in order to use the syslog(8)
299     facility. Create/link the device as needed in the root jail you use.
300
301 6.6 Why can't Pound log directly to a file?
302
303     This is a security requirement. As things stand, Pound does not write at
304     all to the disk. The existing tools - such as syslog - allow all the
305     flexibility one could wish for.
306
307     If you absolutely must you can try the patches from Shinji Tanaka (see
308     http://www.hatena-inc.co.jp/~stanaka/pound/ for details).
309
310
311 7. WebDAV
312 =========
313
314 7.1 I compiled Pound with DAV support but it still rejects the requests
315
316     You also need to define "WebDAV 1" in your config file, and (depending on
317     your server or application) "xHTTP 1" as well.
318
319 7.3 Can I use Pound as a front-end for Subversion?
320
321     Yes. You may have some problems with using it via HTTPS, but HTTP should
322     work.
323
324
325 8. Zope
326 =======
327
328 8.1 What configurations is Pound most helpful for?
329
330     If you have several servers running on top of a ZEO server, Pound will
331     allow you to load-balance between them (BTW, this was the original
332     motivation for developing Pound). Pound also makes for a very good,
333     light-weight front-end for a single Zope - exposing the Zope Web-server
334     directly on the big, bad Internet is not a very good idea.
335
336 8.2 Can I have virtual hosts in Zope without Apache?
337
338     Yes. Despite persistent rumors, the Virtual Host Monster works perfectly
339     well on its own (dark incantations at midnight under the shade of the
340     cross-shaped oak branch are NOT required). All you need to do is to
341     add a VHM in the Zope root, click on the Mappings tab and add whatever
342     hosts you need.
343
344 8.3 Can I have HTTPS for Zope?
345
346     Yes. Pound will happily pass SSL requests to Zope. You have three possible
347     methods to force Zope to generate responses with the https:// prefix:
348
349     - if all you need is a specific area to be accessible only through HTTPS
350       you can add a SiteRoot with the correct name.
351
352     - alternately the Pound distribution includes patches for z2.py that
353       include a new -y flag for a "https://" port.
354
355     - finally, for version 2.7 or later you can set it in zope.conf.
356
357 8.4 Can I force HTTPS for certain areas in Zope?
358
359     Yes. Add a check for the SSL-specific headers in the dtml_header or
360     whatever equivalent you use. See the details on HTTPSHeaders in the man
361     page.
362
363
364 9. Miscellaneous/MS
365 ===================
366
367 9.1 IE fails to connect to Pound via HTTPS
368
369     Define the ciphers to be
370     
371         "ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL"
372
373     in the config file. We have had reports of IE problems with other
374     ciphers.
375
376 9.2 IE has big delays in getting replies from Pound
377
378     Try a shorter Client timeout. IE uses exactly 4 sockets, and as long as
379     they stay open it won't do anything else. A short Client value will
380     force the socket(s) to be closed earlier, thus avoiding annoying waits.
381
382 9.3 I try to run MS OWA and Pound rejects the requests
383
384     Make sure you configured Pound with --enable-msdav. Make sure you
385     included "WebDAV 1" in the config file. Pray that MS would adhere to
386     some known standard. Repeat as necessary.
387
388 9.4 How can I force OWA to accept HTTPS requests?
389
390     Make sure to define
391
392         AddHeader   "Front-End-Https: on"
393
394     in the config file. This will force OWA to generate the responses with
395     the correct protocol.