Set a better default ciphers list if none was specified.
[pound.git] / pound.8
1 .TH POUND "8" "Jan 2010" "pound" "System Manager's Manual"
2 .SH NAME
3 pound \- HTTP/HTTPS reverse-proxy and load-balancer
4 .SH SYNOPSIS
5 .TP
6 .B pound
7 [\fI-v\fR]
8 [\fI-c\fR]
9 [\fI-V\fR]
10 [\fI-f config_file\fR]
11 [\fI-p pid_file\fR]
12 .SH DESCRIPTION
13 .PP
14 .B Pound
15 is a reverse-proxy load balancing server. It accepts requests from HTTP/HTTPS
16 clients and distributes them to one or more Web servers. The HTTPS requests are
17 decrypted and passed to the back-ends as plain HTTP.
18 .PP
19 If more than one back-end server is defined,
20 .B Pound
21 chooses one of them randomly, based on defined priorities. By default,
22 .B Pound
23 keeps track of associations between clients and back-end servers (sessions).
24 .SH GENERAL PRINCIPLES
25 .P
26 In general
27 .B Pound
28 needs three types of objects defined in order to function:
29 .IR listeners ,
30 .I services
31 and
32 .IR back-ends .
33 .TP
34 \fBListeners\fR
35 A
36 .I listener
37 is a definition of how
38 .B Pound
39 receives requests from the clients (browsers). Two types of
40 .I listeners
41 may be defined: regular HTTP
42 .I listeners
43 and HTTPS (HTTP over SSL/TLS)
44 .IR listeners .
45 At the very least a
46 .I listener
47 must define the address and port to listen on, with additional
48 requirements for HTTPS
49 .IR listeners .
50 .TP
51 \fBServices\fR
52 A
53 .I service
54 is the definition of how the requests are answered. The
55 .I services
56 may be defined within a
57 .I listener
58 or at the top level (global). When a request is received
59 .B Pound
60 attempts to match them to each
61 .I service
62 in turn, starting with the
63 .I services
64 defined in the
65 .I listener
66 itself and, if needed, continuing with the
67 .I services
68 defined at the global level. The
69 .I services
70 may define their own conditions as to which requests they can answer:
71 typically this involves certain URLs (images only, or a certain path)
72 or specific headers (such as the Host header). A
73 .I service
74 may also define a
75 .I session
76 mechanism: if defined future requests from a given client will always
77 be answered by the same
78 .IR back-end .
79 .TP
80 \fBBack-ends\fR
81 The
82 .I back-ends
83 are the actual servers for the content requested. By itself,
84 .B Pound
85 supplies no responses - all contents must be received from a "real"
86 web server. The
87 .I back-end
88 defines how the server should be contacted.
89 .IP
90 Three types of
91 .I back-ends
92 may be defined: a "regular"
93 .I back-end
94 which receives requests and returns responses, a "redirect"
95 .I back-end
96 in which case
97 .B Pound
98 will respond with a redirect response, without accessing any
99 .I back-end
100 at all, or an "emergency"
101 .I back-end
102 which will be used only if all other backends are "dead".
103 .IP
104 Multiple
105 .I back-ends
106 may be defined within a
107 .IR service ,
108 in which case
109 .B Pound
110 will load-balance between the available
111 .IR back-ends .
112 .IP
113 If a
114 .I back-end
115 fails to respond it will be considered "dead", in which case
116 .B Pound
117 will stop sending requests to it. Dead
118 .I back-ends
119 are periodically checked for availability, and once they respond again they
120 are "resurected" and requests are sent again their way. If no
121 .I back-ends
122 are available (none were defined, or all are "dead") then
123 .B Pound
124 will reply with "503 Service Unavailable", without checking additional
125 .IR services .
126 .IP
127 The connection between
128 .B Pound
129 and the
130 .I back-ends
131 is always via HTTP, regardless of the actual protocol used between
132 .B Pound
133 and the client.
134 .SH OPTIONS
135 Options available (see also below for configuration file options):
136 .TP
137 \fB\-v\fR
138 Verbose mode: error messages will be sent to stdout even if
139 .B Pound
140 was configured to log to syslog. This applies only to startup messages, before
141 .B Pound
142 puts itself in the background. Normal operational messages will still go to syslog.
143 .TP
144 \fB\-V\fR
145 Print version:
146 .B Pound
147 will exit immediately after printing the current version and configuration flags.
148 .TP
149 \fB\-c\fR
150 Check only:
151 .B Pound
152 will exit immediately after parsing the configuration file. This may be used for
153 running a quick syntax check before actually activating a server.
154 .TP
155 \fB\-f\fR config_file
156 Location of the configuration file (see below for a full description of the format).
157 Default:
158 .I /usr/local/etc/pound.cfg
159 .TP
160 \fB\-p\fR pid_file
161 Location of the pid file.
162 .B Pound
163 will write its own pid into this file. Normally this is used for shell
164 scripts that control starting and stopping of the daemon.
165 Default:
166 .I /var/run/pound.pid
167 .PP
168 In general, any number of back-end servers may be specified. Use the priority to
169 affect the load distribution among unequal-performance servers.
170 .PP
171 One (or more) copies of
172 .B Pound
173 should be started at boot time. Use "big iron" if you expect heavy loads: while
174 .B Pound
175 is as light-weight as I know how to make it, with a lot of simultaneous requests it
176 will use quite a bit of CPU and memory. Multiple CPUs are your friend.
177 .SH "CONFIGURATION FILE"
178 Each line in the file is considered a complete configuration directive. The directives
179 are case-insensitive. Empty lines or lines starting in '#' are ignored. There are three
180 types of directives:
181 .B global
182 directives (they affect the settings for the entire program instance),
183 .B listener
184 directives (they define which requests
185 .B Pound
186 will listen for), and
187 .B service
188 directives (they affect only a specific group of requests).
189 .SH "GLOBAL DIRECTIVES"
190 Global directives may appear anywhere within the configuration file, though it is
191 customary for them to be at the start. They may appear in any order.
192 .TP
193 \fBUser\fR "user_name"
194 Specify the user
195 .B Pound
196 will run as (must be defined in \fI/etc/passwd\fR).
197 .TP
198 \fBGroup\fR "group_name"
199 Specify the group
200 .B Pound
201 will run as (must be defined in \fI/etc/group\fR).
202 .TP
203 \fBRootJail\fR "directory_path_and_name"
204 Specify the directory that
205 .B Pound
206 will chroot to at runtime. Please note that OpenSSL requires access to /dev/urandom,
207 so make sure you create a device by that name, accessible from the root jail
208 directory.
209 .B Pound
210 may also require access to
211 .I /dev/syslog
212 or similar.
213 .TP
214 \fBDaemon\fR 0|1
215 Have
216 .B Pound
217 run in the foreground (if 0) or as a daemon (if 1). By default
218 .B Pound
219 runs as a daemon (detaches itself from the controlling terminal and
220 puts itself in the background). By specifying this option you can force
221 .B Pound
222 to work like a regular process. Useful for debugging or if you want to
223 use something like \fIdaemontools\fR.
224 .TP
225 \fBThreads\fR nnn
226 How many worker threads
227 .B Pound
228 should use. Default: 128. Tune this parameter to improve performance.
229 If you set it too high,
230 .B Pound
231 will use a lot memory, and some CPU will be wasted on context switches.
232 If you set it too low requests may be served with some delay. Experiment
233 to find the optimal value for your installation.
234 .TP
235 \fBLogFacility\fR value
236 Specify the log facility to use.
237 .I value
238 (default: daemon) must be one of the symbolic facility names defined in
239 \fIsyslog.h\fR. This facility shall be used for logging. Using a - for
240 the facility name causes
241 .B Pound
242 to log to stdout/stderr.
243 .TP
244 \fBLogLevel\fR value
245 Specify the logging level: 0 for no logging, 1 (default) for regular
246 logging, 2 for extended logging (show chosen backend server as well),
247 3 for Apache-like format (Combined Log Format with Virtual Host), 4
248 (same as 3 but without the virtual host information) and 5 (same as 4
249 but with information about the
250 .I Service
251 and
252 .I BackEnd
253 used).
254 This value can be overridden for specific listeners.
255 .TP
256 \fBIgnoreCase\fR 0|1
257 Ignore case when matching URLs (default: 0). This value can be
258 overridden for specific services.
259 .TP
260 \fBDynScale\fR 0|1
261 Enable or disable the dynamic rescaling code (default: 0). If enabled
262 .B Pound
263 will periodically try to modify the back-end priorities in order to
264 equalise the response times from the various back-ends.
265 This value can be overridden for specific services.
266 .TP
267 \fBAlive\fR value
268 Specify how often
269 .B Pound
270 will check for resurected back-end hosts (default: 30 seconds). In
271 general, it is a good idea to set this as low as possible - it
272 will find resurected hosts faster. However, if you set it too
273 low it will consume resources - so beware.
274 .TP
275 \fBClient\fR value
276 Specify for how long
277 .B Pound
278 will wait for a client request (default: 10 seconds). After this
279 long has passed without the client sending any data
280 .B Pound
281 will close the connection. Set it higher if your clients
282 time-out on a slow network or over-loaded server, lower if you
283 start getting DOS attacks or run into problems with IE clients.
284 This value can be overridden for specific listeners.
285 .TP
286 \fBTimeOut\fR value
287 How long should
288 .B Pound
289 wait for a response from the back-end (in seconds). Default: 15 seconds.
290 This value can be overridden for specific back-ends.
291 .TP
292 \fBConnTO\fR value
293 How long should
294 .B Pound
295 wait for a connection to the back-end (in seconds). Default: the
296 .B TimeOut
297 value. This value can be overridden for specific back-ends.
298 .TP
299 \fBGrace\fR value
300 How long should
301 .B Pound
302 continue to answer existing connections after a receiving and INT or HUP
303 signal (default: 30 seconds). The configured listeners are closed
304 immediately. You can bypass this behaviour by stopping
305 .B Pound
306 with a TERM or QUIT signal, in which case the program exits without any
307 delay.
308 .TP
309 \fBSSLEngine\fR "name"
310 Use an OpenSSL hardware acceleration card called \fIname\fR. Available
311 only if OpenSSL-engine is installed on your system.
312 .TP
313 \fBECDHcurve\fR "name"
314 Use the named curve for elliptical curve encryption (default: prime256v1).
315 .TP
316 \fBControl\fR "/path/to/socket"
317 Set the control socket path. If not defined
318 .B Pound
319 does not listen for any commands. The commands may be issued by using
320 the
321 .I poundctl(8)
322 program.
323 .TP
324 \fBInclude\fR "/path/to/file"
325 Include the file as though it were part of the configuration file.
326 .TP
327 \fBAnonymise\fR
328 Replace the last byte of the client address with 0 for logging purposes.
329 Default: log the client address in full.
330 .SH "HTTP Listener"
331 An HTTP listener defines an address and port that
332 .B Pound
333 will listen on for HTTP requests. All configuration directives enclosed
334 between
335 .I ListenHTTP
336 and
337 .I End
338 are specific to a single HTTP listener. At the very least you must specify
339 and address and a port for each listener. The following directives are
340 available:
341 .TP
342 \fBAddress\fR address
343 The address that
344 .B Pound
345 will listen on. This can be a numeric IP address, or a symbolic host name
346 that must be resolvable at run-time.  This is a
347 .B mandatory
348 parameter. The address 0.0.0.0 may be used as an alias for 'all available
349 addresses on this machine', but this practice is strongly discouraged, as
350 it will interfere with the rewriting mechanisms (see below).
351 .TP
352 \fBPort\fR port
353 The port number that
354 .B Pound
355 will listen on.  This is a
356 .B mandatory
357 parameter.
358 .TP
359 \fBxHTTP\fR value
360 Defines which HTTP verbs are accepted. The possible values are:
361 .IP
362 .I 0
363 (default) accept only standard HTTP requests (GET, POST, HEAD).
364 .IP
365 .I 1
366 additionally allow extended HTTP requests (PUT, PATCH, DELETE).
367 .IP
368 .I 2
369 additionally allow standard WebDAV verbs (LOCK, UNLOCK, PROPFIND,
370 PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY,
371 CHECKOUT, MERGE, REPORT, MKCALENDAR).
372 .IP
373 .I 3
374 additionally allow MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE,
375 NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).
376 .IP
377 .I 4
378 additionally allow MS RPC extensions verbs (RPC_IN_DATA, RPC_OUT_DATA).
379 .TP
380 \fBClient\fR value
381 Override the global
382 .I Client
383 time-out value.
384 .TP
385 \fBCheckURL\fR "pattern to match"
386 Define a pattern that must be matched by each request sent to this
387 listener. A request that does not match is considered to be illegal.
388 By default
389 .B Pound
390 accepts all requests (i.e. the pattern is ".*"), but you are free to
391 limit it to something more reasonable. Please note that this applies
392 only to the request path -
393 .B Pound
394 will still check that the request is syntactically correct.
395 .TP
396 \fBErr414\fR "filename"
397 A file with the text to be displayed if an Error 414 occurs.
398 Default: "Request URI is too long.".
399 .TP
400 \fBErr500\fR "filename"
401 A file with the text to be displayed if an Error 500 occurs.
402 Default: "An internal server error occurred. Please try again later.".
403 .TP
404 \fBErr501\fR "filename"
405 A file with the text to be displayed if an Error 501 occurs.
406 Default: "This method may not be used.".
407 .TP
408 \fBErr503\fR "filename"
409 A file with the text to be displayed if an Error 503 occurs.
410 Default: "The service is not available. Please try again later.".
411 .TP
412 \fBMaxRequest\fR nnn
413 Request maximal size. All requests will be limited to these many bytes. If
414 a request contains more data than allowed an error 414 is returned. Default:
415 unlimited.
416 .TP
417 \fBHeadRemove\fR "header pattern"
418 Remove certain headers from the incoming requests. All occurences of the
419 matching specified header will be removed. Please note that this filtering
420 is done prior to other checks (such as \fIHeadRequire\fR or \fIHeadDeny\fR),
421 so you should not try to check for these headers in later matches. Multiple
422 directives may be specified in order to remove more than one header, and
423 the header itself may be a regular pattern (though this should be used with
424 caution).
425 .TP
426 \fBAddHeader\fR "header: to add"
427 Add the defined header to the request passed to the back-end server. The header
428 is added verbatim. Use multiple \fIAddHeader\fR directives if you need to add more
429 than one header.
430 .TP
431 \fBRewriteLocation\fR 0|1|2
432 If 1 force
433 .B Pound
434 to change the Location: and Content-location: headers in responses. If they
435 point to the back-end itself or to the listener (but with the wrong protocol)
436 the response will be changed to show the virtual host in the request. Default:
437 1 (active).  If the value is set to 2 only the back-end address is compared;
438 this is useful for redirecting a request to an HTTPS listener on
439 the same server as the HTTP listener.
440 .TP
441 \fBRewriteDestination\fR 0|1
442 If 1 force
443 .B Pound
444 to change the Destination: header in requests. The header is changed to point
445 to the back-end itself with the correct protocol. Default: 0.
446 .TP
447 \fBLogLevel\fR value
448 Override the global
449 .I LogLevel
450 value.
451 .TP
452 \fBService\fR [ "name" ]
453 This defines a private service (see below for service definition syntax). This
454 service will be used only by this listener. The service may be optionally
455 named, with the name showing in the
456 .I poundctl
457 listings.
458 .SH "HTTPS Listener"
459 An HTTPS listener defines an address and port that
460 .B Pound
461 will listen on for HTTPS requests. All configuration directives enclosed
462 between
463 .I ListenHTTPS
464 and
465 .I End
466 are specific to a single HTTPS listener. At the very least you must specify
467 and address, a port and a server certificate for each listener. All directives
468 defined for HTTP listeners are applicable to HTTPS listeners as well. The
469 following additional directives are also available:
470 .TP
471 \fBCert\fR "certificate file"
472 Specify the server certificate. The
473 .I certificate file
474 is the file containing the certificate, possibly a certificate chain and the signature
475 for this server. This directive is
476 .B mandatory
477 for HTTPS listeners.
478 .IP
479 Please note that multiple
480 .I Cert
481 directives are allowed if your OpenSSL version supports SNI. In such cases,
482 the first directive is the default certificate, with additional certificates
483 used if the client requests them.
484 .IP
485 The ordering of the directives is important: the first certificate where the CN
486 matches the client request will be used, so put your directives in the
487 most-specific-to-least specific order (i.e. wildcard certificates
488 .B after
489 host-specific certificates).
490 .IP
491 .I Cert
492 directives
493 .B must
494 precede all other SSL-specific directives.
495 .TP
496 \fBClientCert\fR 0|1|2|3 depth
497 Ask for the client's HTTPS certificate: 0 - don't ask (default), 1 - ask,
498 2 - ask and fail if no certificate was presented, 3 - ask but do not verify.
499 .I Depth
500 is the depth of verification for a client certificate (up to 9). The default
501 depth limit is 9, allowing for the peer certificate and additional 9 CA
502 certificates that must be verified.
503 .TP
504 \fBDisable\fR SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
505 Disable the protocol \fBand all lower protocols as well\fR.
506 This is due to a limitation in OpenSSL, which does not support disabling a single
507 protocol. For example,
508 .I Disable TLSv1
509 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
510 .TP
511 \fBCiphers\fR "acceptable:cipher:list"
512 This is the list of ciphers that will be accepted by the SSL connection; it is a
513 string in the same format as in OpenSSL
514 .I ciphers(1)
515 and
516 .I SSL_CTX_set_cipher_list(3).
517 .TP
518 \fBSSLHonorCipherOrder\fR 0|1
519 If this value is 1, the server will broadcast a preference to use \fBCiphers\fR in
520 the order supplied in the \fBCiphers\fR directive.  If the value is 0, the server
521 will treat the Ciphers list as the list of Ciphers it will accept, but no preference
522 will be indicated.  Default value is 0.
523 .TP
524 \fBSSLAllowClientRenegotiation\fR 0|1|2
525 If this value is 0, client initiated renegotiation will be disabled.  This will
526 mitigate DoS exploits based on client renegotiation, regardless of the patch status
527 of clients and servers related to "Secure renegotiation".  If the value is 1, secure
528 renegotiation is supported.  If the value is 2, insecure renegotiation is supported,
529 with unpatched clients. \fBThis can lead to a DoS and a Man in the Middle attack!\fR
530 The default value is 0.
531 .TP
532 \fBCAlist\fR "CAcert_file"
533 Set the list of "trusted" CA's for this server. The CAcert_file is a file containing
534 a sequence of CA certificates (PEM format). The names of the defined CA certificates
535 will be sent to the client on connection.
536 .TP
537 \fBVerifyList\fR "Verify_file"
538 Set the CA (Certificate Authority). The Verify_file is a file that contains the CA
539 root certificates (in PEM format).
540 .IP
541 .IR "Please note":
542 there is an important difference between the CAlist and the VerifyList. The
543 CAlist tells the client (browser) which client certificates it should send. The
544 VerifyList defines which CAs are actually used for the verification of the
545 returned certificate.
546 .TP
547 \fBCRLlist\fR "CRL_file"
548 Set the CRL (Certificate Revocation List) file. The CRL_file is a file that contains
549 the CRLs (in PEM format).
550 .TP
551 \fBNoHTTPS11\fR 0|1|2
552 Behave like an HTTP/1.0 server for HTTPS clients. If this value is
553 0 disable the check. If the value is 1 do not allow multiple
554 requests on SSL connections. If the value is 2 (default) disable multiple
555 requests on SSL connections only for MSIE clients. Required
556 work-around for a bug in certain versions of IE.
557 .SH "Service"
558 A service is a definition of which back-end servers
559 .B Pound
560 will use to reply to incoming requests. A service may be defined as part
561 of a listener (in which case it will be used only by that listener), or
562 globally (which makes it available to all listeners).
563 .B Pound
564 will always try the private services in the order defined, followed by
565 the global ones.
566 .P
567 All configuration directives enclosed between
568 .I Service
569 and
570 .I End
571 are specific to a single service. The following directives are available:
572 .TP
573 \fBURL\fR "pattern"
574 Match the incoming request. If a request fails to match than this service
575 will be skipped and next one tried. If all services fail to match
576 .B Pound
577 returns an error. You may define multiple
578 .I URL
579 conditions per service, in which case
580 .B all
581 patterns must match. If no
582 .I URL
583 was defined then all requests match. The matching is by default case-sensitive,
584 but this can be overridden by specifying
585 .B IgnoreCase 1
586 .TP
587 \fBIgnoreCase\fR 0|1
588 Override the global
589 .B IgnoreCase
590 setting.
591 .TP
592 \fBHeadRequire\fR "pattern"
593 The request must contain at least on header matching the given pattern.
594 Multiple
595 .I HeadRequire
596 directives may be defined per service, in which case all of them must
597 be satisfied.
598 .TP
599 \fBHeadDeny\fR "pattern"
600 The request may
601 .B not
602 contain any header matching the given pattern.  Multiple
603 .I HeadDeny
604 directives may be defined per service, in which case all of them must be satisfied.
605 .IP
606 .IR "Please note":
607 if the listener defined a
608 .I HeadRemove
609 directive, the matching headers are removed
610 .B before
611 the service matching is attempted.
612 .TP
613 \fBDynScale\fR 0|1
614 Enable or disable dynamic rescaling for the current service. This value will
615 override the value globally defined.
616 .TP
617 \fBDisabled\fR 0|1
618 Start
619 .B Pound
620 with this service disabled (1) or enabled (0). If started as disabled, the
621 service can be later enabled with
622 .I poundctl
623 (8).
624 .TP
625 \fBBackEnd\fR
626 Directives enclosed between a
627 .I BackEnd
628 and
629 the following
630 .I End
631 directives define a single back-end server (see below for details). You may define
632 multiple back-ends per service, in which case
633 .B Pound
634 will attempt to load-balance between them.
635 .TP
636 \fBRedirect\fR [code] "url"
637 This is a special type of back-end. Instead of sending the request to a back-end
638 .B Pound
639 replies immediately with a redirection to the given URL. You may define multiple
640 redirectors in a service, as well as mixing them with regular back-ends.
641 .IP
642 The address the client is redirected to is determined by the actual
643 .I url
644 you specify: if it is a "pure" host (i.e. with no path) then the client will be
645 redirected to the host you specified, with the original request path appended. If
646 your
647 .I url
648 does contain a path then the request path is ignored.
649 .IP
650 Examples: if you specified
651 .br
652
653 .br
654     Redirect "http://abc.example"
655 .br
656
657 .br
658 and the client requested
659 .I http://xyz/a/b/c
660 then it will be redirected to
661 .IR "http://abc.example/a/b/c",
662 but if you specified
663 .br
664
665 .br
666     Redirect "http://abc.example/index.html"
667 .br
668
669 .br
670 it will be sent to
671 .IR "http://abc.example/index.html".
672 .IP
673 .IR "Technical note":
674 in an ideal world
675 .B Pound
676 should reply with a "307 Temporary Redirect" status. Unfortunately, that is not
677 yet supported by all clients (in particular HTTP 1.0 ones), so
678 .B Pound
679 currently replies by default with a "302 Found" instead. You may override this
680 behaviour by specifying the code to be used (301, 302 or 307).
681 .TP
682 \fBEmergency\fR
683 Directives enclosed between an
684 .I Emergency
685 and
686 the following
687 .I End
688 directives define an emergency back-end server (see below for details). You may define
689 only one emergency server per service, which
690 .B Pound
691 will attempt to use if all backends are down.
692 .TP
693 \fBSession\fR
694 Directives enclosed between a
695 .I Session
696 and
697 the following
698 .I End
699 directives define a session-tracking mechanism for the current service. See below
700 for details.
701 .SH "BackEnd"
702 A back-end is a definition of a single back-end server
703 .B Pound
704 will use to reply to incoming requests.  All configuration directives enclosed between
705 .I BackEnd
706 and
707 .I End
708 are specific to a single service. The following directives are available:
709 .TP
710 \fBAddress\fR address
711 The address that
712 .B Pound
713 will connect to. This can be a numeric IP address, or a symbolic host name
714 that must be resolvable at run-time. If the name cannot be resolved to a valid
715 address,
716 .B Pound
717 will assume that it represents the path for a Unix-domain socket. This is a
718 .B mandatory
719 parameter.
720 .TP
721 \fBPort\fR port
722 The port number that
723 .B Pound
724 will connect to. This is a
725 .B mandatory
726 parameter for non Unix-domain back-ends.
727 .TP
728 \fBHTTPS\fR
729 The back-end is using HTTPS.
730 .TP
731 \fBCert\fR "certificate file"
732 Specify the certificate that
733 .B Pound
734 will use as a client. The
735 .I certificate file
736 is the file containing the certificate, possibly a certificate chain and the signature.
737 This directive may appear only after the
738 .I HTTPS
739 directive.
740 .TP
741 \fBDisable\fR SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
742 Disable the protocol \fBand all lower protocols as well\fR.
743 This is due to a limitation in OpenSSL, which does not support disabling a single
744 protocol. For example,
745 .I Disable TLSv1
746 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
747 This directive may appear only after the
748 .I HTTPS
749 directive.
750 .TP
751 \fBCiphers\fR "acceptable:cipher:list"
752 This is the list of ciphers that will be accepted by the SSL connection; it is a
753 string in the same format as in OpenSSL
754 .I ciphers(1)
755 and
756 .I SSL_CTX_set_cipher_list(3).
757 This directive may appear only after the
758 .I HTTPS
759 directive.
760 .TP
761 \fBPriority\fR val
762 The priority of this back-end (between 1 and 9, 5 is default). Higher priority
763 back-ends will be used more often than lower priority ones, so you should
764 define higher priorities for more capable servers.
765 .TP
766 \fBTimeOut\fR val
767 Override the global
768 .I TimeOut
769 value.
770 .TP
771 \fBConnTO\fR val
772 Override the global
773 .I ConnTO
774 value.
775 .TP
776 \fBHAport\fR [ address ] port
777 A port (and optional address) to be used for server function checks. See below
778 the "High Availability" section for a more detailed discussion. By default
779 .B Pound
780 uses the same address as the back-end server, but you may use a separate address
781 if you wish. This directive applies only to non Unix-domain servers.
782 .TP
783 \fBDisabled\fR 0|1
784 Start
785 .B Pound
786 with this back-end disabled (1) or enabled (0). If started as disabled, the
787 back-end can be later enabled with
788 .I poundctl
789 (8).
790 .SH "Emergency"
791 The emergency server will be used once all existing back-ends are "dead".
792 All configuration directives enclosed between
793 .I Emergency
794 and
795 .I End
796 are specific to a single service. The following directives are available:
797 .TP
798 \fBAddress\fR address
799 The address that
800 .B Pound
801 will connect to. This can be a numeric IP address, or a symbolic host name
802 that must be resolvable at run-time. If the name cannot be resolved to a valid
803 address,
804 .B Pound
805 will assume that it represents the path for a Unix-domain socket. This is a
806 .B mandatory
807 parameter.
808 .TP
809 \fBPort\fR port
810 The port number that
811 .B Pound
812 will connect to. This is a
813 .B mandatory
814 parameter for non Unix-domain back-ends.
815 .SH "Session"
816 Defines how a service deals with possible HTTP sessions.  All configuration
817 directives enclosed between
818 .I Session
819 and
820 .I End
821 are specific to a single service. Once a sessions is identified,
822 .B Pound
823 will attempt to send all requests within that session to the same back-end
824 server.
825 .PP
826 The following directives are available:
827 .TP
828 \fBType\fR IP|BASIC|URL|PARM|COOKIE|HEADER
829 What kind of sessions are we looking for: IP (the client address), BASIC (basic
830 authentication), URL (a request parameter), PARM (a URI parameter), COOKIE (a
831 certain cookie), or HEADER (a certain request header).
832 This is a
833 .B mandatory
834 parameter.
835 .TP
836 \fBTTL\fR seconds
837 How long can a session be idle (in seconds). A session that has been idle for
838 longer than the specified number of seconds will be discarded.
839 This is a
840 .B mandatory
841 parameter.
842 .TP
843 \fBID\fR "name"
844 The session identifier. This directive is permitted only for sessions of type
845 URL (the name of the request parameter we need to track), COOKIE (the name of
846 the cookie) and HEADER (the header name).
847 .PP
848 See below for some examples.
849 .SH HIGH-AVAILABILITY
850 .B Pound
851 attempts to keep track of active back-end servers, and will temporarily disable
852 servers that do not respond (though not necessarily dead: an overloaded server
853 that
854 .B Pound
855 cannot establish a connection to will be considered dead). However, every
856 .I Alive
857 seconds, an attempt is made to connect to the dead servers in case they have become
858 active again. If this attempt succeeds, connections will be initiated to them again.
859 .PP
860 In general it is a good idea to set this time interval as low as is consistent with
861 your resources in order to benefit from resurected servers at the earliest possible
862 time. The default value of 30 seconds is probably a good choice.
863 .PP
864 The clients that happen upon a dead backend server will just receive a
865 .I "503 Service Unavailable"
866 message.
867 .PP
868 The
869 .I HAport
870 parameter specifies an additional port (and optionally an address)
871 that is used only for viability checks: if this port is specified in a
872 .I BackEnd
873 directive,
874 .B Pound
875 will attempt periodically (every
876 .I Alive
877 seconds) to connect to this port. If the port does not respond the server is considered dead.
878 .B "It never makes sense to have the"
879 .I HAport
880 .B "identical to the main back-end port:"
881 this would only generate extra, unncecessary activity (CPU, network traffic) for no good
882 reason whatsoever.  The
883 .I HAport
884 is meant for applications that offer an additional health monitoring port or for installations
885 that wish to take servers off-line in a controlled manner.
886 .PP
887 By default the address of the
888 .I HAport
889 health monitor is the same as that of the
890 back-end server. You may specify a different address though, for example if you have
891 a monitoring program running on another host.
892 .SH HTTPS HEADERS
893 If a client browser connects to
894 .B Pound
895 via HTTPS and if it presents a client certificate
896 .B Pound
897 adds the following headers to the request it issues to the server:
898 .TP
899 \fBX-SSL-Subject\fR
900 Details about the certificate owner.
901 .TP
902 \fBX-SSL-Issuer\fR
903 Details about the certificate issuer (Certificate Authority).
904 .TP
905 \fBX-SSL-notBefore\fR
906 Starting date of certificate validity.
907 .TP
908 \fBX-SSL-notAfter\fR
909 Ending date of certificate validity.
910 .TP
911 \fBX-SSL-serial\fR
912 Certificate serial number (decimal).
913 .TP
914 \fBX-SSL-cipher\fR
915 The cipher currently in use.
916 .TP
917 \fBX-SSL-certificate\fR
918 The full client certificate (PEM-format multi-line)
919 .PP
920 It is the application's responsibility to actually use these
921 headers - Pound just passes this information without checking
922 it in any way (except for signature and encryption correctness).
923 .SH SECURITY
924 .PP
925 In general,
926 .B Pound
927 does not read or write to the hard-disk. The exceptions are reading the configuration file
928 and (possibly) the server certificate file(s) and error message(s), which are opened read-only
929 on startup, read,
930 and closed, and the pid file which is opened on start-up, written to and immediately closed.
931 Following this there is no disk access whatsoever, so using a RootJail directive is only
932 for extra security bonus points.
933 .PP
934 .B Pound
935 tries to sanitise all HTTP/HTTPS requests: the request itself, the headers and the contents
936 are checked for conformance to the RFC's and only valid requests are passed to the back-end
937 servers. This is not absolutely fool-proof - as the recent Apache problem with chunked
938 transfers demonstrated. However, given the current standards, this is the best that can
939 be done - HTTP is an inherently weak protocol.
940 .SH ADDITIONAL NOTES
941 .B Pound
942 uses the system log for messages (default facility LOG_DAEMON). The format is very similar to
943 other web servers, so that if you want to use a log tool:
944 .TP
945     fgrep pound /var/log/messages | your_log_tool
946 .PP
947 Translating HTTPS to HTTP is an iffy proposition: no client information is passed to
948 the server itself (certificates, etc) and the backend server may be misled if it
949 uses absolute URLs. A patch for \fIZope\fR is included in the distribution to address
950 this issue - for other Web servers you are on your own. May the source be with you.
951 .PP
952 .B Pound
953 deals with (and sanitizes) HTTP/1.1 requests. Thus even if you have an HTTP/1.0 server,
954 a single connection to an HTTP/1.1 client is kept, while the connection to the back-end
955 server is re-opened as necessary.
956 .PP
957 .B Pound
958 attempts to resolve the names of the hosts that appear in various requests and/or responses.
959 That means it need a functioning resolver of some kind (be it /etc/hosts, DNS or something
960 else).
961 .SH EXAMPLES
962 To translate HTTPS requests to a local HTTP server (assuming your network address
963 is 123.123.123.123):
964 .IP
965 ListenHTTPS
966 .br
967     Address 1.2.3.4
968 .br
969     Port    443
970 .br
971     Cert    "/etc/pound/server.pem"
972 .br
973
974 .br
975     Service
976 .br
977         BackEnd
978 .br
979             Address 127.0.0.1
980 .br
981             Port    80
982 .br
983         End
984 .br
985     End
986 .br
987 End
988 .PP
989 To distribute the HTTP/HTTPS requests to three Web servers, where the third one
990 is a newer and faster machine:
991 .IP
992 ListenHTTP
993 .br
994     Address 123.123.123.123
995 .br
996     Port    80
997 .br
998 End
999 .br
1000 ListenHTTPS
1001 .br
1002     Address 1.2.3.4
1003 .br
1004     Port    443
1005 .br
1006     Cert    "/etc/pound/server.pem"
1007 .br
1008 End
1009 .br
1010
1011 .br
1012 Service
1013 .br
1014     BackEnd
1015 .br
1016         Address 192.168.0.10
1017 .br
1018         Port    80
1019 .br
1020     End
1021 .br
1022     BackEnd
1023 .br
1024         Address 192.168.0.11
1025 .br
1026         Port    80
1027 .br
1028     End
1029 .br
1030     BackEnd
1031 .br
1032         Address 192.168.0.12
1033 .br
1034         Port    80
1035 .br
1036         Priority 3
1037 .br
1038     End
1039 .br
1040 End
1041 .PP
1042 To separate between image requests and other Web content and send all requests
1043 for a specific URL to a secure server:
1044 .IP
1045 ListenHTTP
1046 .br
1047     Address 123.123.123.123
1048 .br
1049     Port    80
1050 .br
1051 End
1052 .br
1053
1054 .br
1055 # Images server(s)
1056 .br
1057 Service
1058 .br
1059     URL ".*.(jpg|gif)"
1060 .br
1061     BackEnd
1062 .br
1063         Address 192.168.0.12
1064 .br
1065         Port    80
1066 .br
1067     End
1068 .br
1069 End
1070 .br
1071
1072 .br
1073 # redirect all requests for /forbidden
1074 .br
1075 Service
1076 .br
1077     Url         "/forbidden.*"
1078 .br
1079     Redirect    "https://xyzzy.com"
1080 .br
1081 End
1082 .br
1083
1084 .br
1085 # Catch-all server(s)
1086 .br
1087 Service
1088 .br
1089     BackEnd
1090 .br
1091         Address 192.168.0.10
1092 .br
1093         Port    80
1094 .br
1095     End
1096 .br
1097     BackEnd
1098 .br
1099         Address 192.168.0.11
1100 .br
1101         Port    80
1102 .br
1103     End
1104 .br
1105     Session
1106 .br
1107         Type    BASIC
1108 .br
1109         TTL     300
1110 .br
1111     End
1112 .br
1113 End
1114 .PP
1115 Here is a more complex example: assume your static images (GIF/JPEG) are to be served
1116 from a single back-end 192.168.0.10. In addition, 192.168.0.11 is to do the
1117 hosting for www.myserver.com with URL-based sessions, and 192.168.0.20 (a 1GHz PIII)
1118 and 192.168.0.21 (800Mhz Duron) are for all other requests (cookie-based sessions).
1119 The logging will be done by the back-end servers.  The configuration file may look like this:
1120 .IP
1121 User        "nobody"
1122 .br
1123 Group       "nogroup"
1124 .br
1125 RootJail    "/var/pound/jail"
1126 .br
1127 Alive       60
1128 .br
1129 LogLevel    0
1130 .br
1131
1132 .br
1133 # Main listening ports
1134 .br
1135 ListenHTTP
1136 .br
1137     Address 1.2.3.4
1138 .br
1139     Port    80
1140 .br
1141     Client  10
1142 .br
1143 End
1144 .br
1145 ListenHTTPS
1146 .br
1147     Address 1.2.3.4
1148 .br
1149     Port    443
1150 .br
1151     Cert    "/etc/pound/pound.pem"
1152 .br
1153     Client  20
1154 .br
1155 End
1156 .br
1157
1158 .br
1159 # Image server
1160 .br
1161 Service
1162 .br
1163     URL ".*.(jpg|gif)"
1164 .br
1165     BackEnd
1166 .br
1167         Address 192.168.0.10
1168 .br
1169         Port    80
1170 .br
1171     End
1172 .br
1173 End
1174 .br
1175
1176 .br
1177 # Virtual host www.myserver.com
1178 .br
1179 Service
1180 .br
1181     URL         ".*sessid=.*"
1182 .br
1183     HeadRequire "Host:.*www.myserver.com.*"
1184 .br
1185     BackEnd
1186 .br
1187         Address 192.168.0.11
1188 .br
1189         Port    80
1190 .br
1191     End
1192 .br
1193     Session
1194 .br
1195         Type    URL
1196 .br
1197         ID      "sessid"
1198 .br
1199         TTL     120
1200 .br
1201     End
1202 .br
1203 End
1204 .br
1205
1206 .br
1207 # Everybody else
1208 .br
1209 Service
1210 .br
1211     BackEnd
1212 .br
1213         Address 192.168.0.20
1214 .br
1215         Port    80
1216 .br
1217         Priority 5
1218 .br
1219     End
1220 .br
1221     BackEnd
1222 .br
1223         Address 192.168.0.21
1224 .br
1225         Port    80
1226 .br
1227         Priority 4
1228 .br
1229     End
1230 .br
1231     Session
1232 .br
1233         Type    COOKIE
1234 .br
1235         ID      "userid"
1236 .br
1237         TTL     180
1238 .br
1239     End
1240 .br
1241 End
1242 .br
1243 .SH FILES
1244 .TP
1245 \fI/var/run/pound.nnn\fR
1246 this is where
1247 .B Pound
1248 will attempt to record its process id.
1249 .TP
1250 \fI/usr/local/etc/pound.cfg\fR
1251 the default configuration file (the location may be changed when compiling - see the
1252 F_CONF flag in the Makefile).
1253 .TP
1254 \fI/usr/local/etc/pound/cert.pem\fR
1255 the certificate file(s) for HTTPS. The location must be defined in the configuration
1256 file - this is only a suggestion. The file must contain a PEM-encoded certificate,
1257 optionally a certificate chain from a known Certificate Authority to your server certificate
1258 and a PEM-encoded private key (not password protected). See
1259 .I OpenSSL(1)
1260 for details. This file should be well protected, lest someone gets your server
1261 private key.
1262 .SH AUTHOR
1263 Written by Robert Segall, Apsis GmbH.
1264 .SH "REPORTING BUGS"
1265 Report bugs to <roseg@apsis.ch>.
1266 .SH COPYRIGHT
1267 Copyright \(co 2002-2010 Apsis GmbH.
1268 .br
1269 This is free software; see the source for copying conditions.  There is NO
1270 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.