1POUND(8) System Manager's Manual POUND(8)
2
6 pound - HTTP/HTTPS reverse-proxy and load-balancer
7
9 pound [-v] [-c] [-V] [-f config_file] [-p pid_file]
10
12 Pound is a reverse-proxy load balancing server. It accepts requests
13 from HTTP/HTTPS clients and distributes them to one or more Web
14 servers. The HTTPS requests are decrypted and passed to the back-ends
15 as plain HTTP.
16 If more than one back-end server is defined, Pound chooses one of them
18 randomly, based on defined priorities. By default, Pound keeps track of
19 associations between clients and back-end servers (sessions).
20
22 In general Pound needs three types of objects defined in order to func‐
23 tion: listeners, services and back-ends.
24 Listeners
26 A listener is a definition of how Pound receives requests from
27 the clients (browsers). Two types of listeners may be defined:
28 regular HTTP listeners and HTTPS (HTTP over SSL/TLS) listeners.
29 At the very least a listener must define the address and port to
30 listen on, with additional requirements for HTTPS listeners.
31 Services
33 A service is the definition of how the requests are answered.
34 The services may be defined within a listener or at the top
35 level (global). When a request is received Pound attempts to
36 match them to each service in turn, starting with the services
37 defined in the listener itself and, if needed, continuing with
38 the services defined at the global level. The services may
39 define their own conditions as to which requests they can
40 answer: typically this involves certain URLs (images only, or a
41 certain path) or specific headers (such as the Host header). A
42 service may also define a session mechanism: if defined future
43 requests from a given client will always be answered by the same
44 back-end.
45 Back-ends
47 The back-ends are the actual servers for the content requested.
48 By itself, Pound supplies no responses - all contents must be
49 received from a "real" web server. The back-end defines how the
50 server should be contacted.
51 Three types of back-ends may be defined: a "regular" back-end
53 which receives requests and returns responses, a "redirect"
54 back-end in which case Pound will respond with a redirect
55 response, without accessing any back-end at all, or an "emer‐
56 gency" back-end which will be used only if all other backends
57 are "dead".
58 Multiple back-ends may be defined within a service, in which
60 case Pound will load-balance between the available back-ends.
61 If a back-end fails to respond it will be considered "dead", in
63 which case Pound will stop sending requests to it. Dead back-
64 ends are periodically checked for availability, and once they
65 respond again they are "resurected" and requests are sent again
66 their way. If no back-ends are available (none were defined, or
67 all are "dead") then Pound will reply with "503 Service Unavail‐
68 able", without checking additional services.
69 The connection between Pound and the back-ends is always via
71 HTTP, regardless of the actual protocol used between Pound and
72 the client.
73
75 Options available (see also below for configuration file options):
76 -v Verbose mode: error messages will be sent to stdout even if
78 Pound was configured to log to syslog. This applies only to
79 startup messages, before Pound puts itself in the background.
80 Normal operational messages will still go to syslog.
81 -V Print version: Pound will exit immediately after printing the
83 current version and configuration flags.
84 -c Check only: Pound will exit immediately after parsing the con‐
86 figuration file. This may be used for running a quick syntax
87 check before actually activating a server.
88 -f config_file
90 Location of the configuration file (see below for a full
91 description of the format). Default: /usr/local/etc/pound.cfg
92 -p pid_file
94 Location of the pid file. Pound will write its own pid into
95 this file. Normally this is used for shell scripts that control
96 starting and stopping of the daemon. Default:
97 /var/run/pound.pid
98 In general, any number of back-end servers may be specified. Use the
100 priority to affect the load distribution among unequal-performance
101 servers.
102 One (or more) copies of Pound should be started at boot time. Use "big
104 iron" if you expect heavy loads: while Pound is as light-weight as I
105 know how to make it, with a lot of simultaneous requests it will use
106 quite a bit of CPU and memory. Multiple CPUs are your friend.
107
109 Each line in the file is considered a complete configuration directive.
110 The directives are case-insensitive. Empty lines or lines starting in
111 '#' are ignored. There are three types of directives: global directives
112 (they affect the settings for the entire program instance), listener
113 directives (they define which requests Pound will listen for), and ser‐
114 vice directives (they affect only a specific group of requests).
115
117 Global directives may appear anywhere within the configuration file,
118 though it is customary for them to be at the start. They may appear in
119 any order.
120 User "user_name"
122 Specify the user Pound will run as (must be defined in
123 /etc/passwd).
124 Group "group_name"
126 Specify the group Pound will run as (must be defined in
127 /etc/group).
128 RootJail "directory_path_and_name"
130 Specify the directory that Pound will chroot to at runtime.
131 Please note that OpenSSL requires access to /dev/urandom, so
132 make sure you create a device by that name, accessible from the
133 root jail directory. Pound may also require access to /dev/sys‐
134 log or similar.
135 Daemon 0|1
137 Have Pound run in the foreground (if 0) or as a daemon (if 1).
138 By default Pound runs as a daemon (detaches itself from the con‐
139 trolling terminal and puts itself in the background). By speci‐
140 fying this option you can force Pound to work like a regular
141 process. Useful for debugging or if you want to use something
142 like daemontools.
143 Threads nnn
145 How many worker threads Pound should use. Default: 128. Tune
146 this parameter to improve performance. If you set it too high,
147 Pound will use a lot memory, and some CPU will be wasted on con‐
148 text switches. If you set it too low requests may be served
149 with some delay. Experiment to find the optimal value for your
150 installation.
151 LogFacility value
153 Specify the log facility to use. value (default: daemon) must
154 be one of the symbolic facility names defined in syslog.h. This
155 facility shall be used for logging. Using a - for the facility
156 name causes Pound to log to stdout/stderr.
157 LogLevel value
159 Specify the logging level: 0 for no logging, 1 (default) for
160 regular logging, 2 for extended logging (show chosen backend
161 server as well), 3 for Apache-like format (Combined Log Format
162 with Virtual Host), 4 (same as 3 but without the virtual host
163 information) and 5 (same as 4 but with information about the
164 Service and BackEnd used). This value can be overridden for
165 specific listeners.
166 IgnoreCase 0|1
168 Ignore case when matching URLs (default: 0). This value can be
169 overridden for specific services.
170 DynScale 0|1
172 Enable or disable the dynamic rescaling code (default: 0). If
173 enabled Pound will periodically try to modify the back-end pri‐
174 orities in order to equalise the response times from the various
175 back-ends. This value can be overridden for specific services.
176 Alive value
178 Specify how often Pound will check for resurected back-end hosts
179 (default: 30 seconds). In general, it is a good idea to set this
180 as low as possible - it will find resurected hosts faster. How‐
181 ever, if you set it too low it will consume resources - so
182 beware.
183 Client value
185 Specify for how long Pound will wait for a client request
186 (default: 10 seconds). After this long has passed without the
187 client sending any data Pound will close the connection. Set it
188 higher if your clients time-out on a slow network or over-loaded
189 server, lower if you start getting DOS attacks or run into prob‐
190 lems with IE clients. This value can be overridden for specific
191 listeners.
192 TimeOut value
194 How long should Pound wait for a response from the back-end (in
195 seconds). Default: 15 seconds. This value can be overridden for
196 specific back-ends.
197 ConnTO value
199 How long should Pound wait for a connection to the back-end (in
200 seconds). Default: the TimeOut value. This value can be overrid‐
201 den for specific back-ends.
202 Grace value
204 How long should Pound continue to answer existing connections
205 after a receiving and INT or HUP signal (default: 30 seconds).
206 The configured listeners are closed immediately. You can bypass
207 this behaviour by stopping Pound with a TERM or QUIT signal, in
208 which case the program exits without any delay.
209 SSLEngine "name"
211 Use an OpenSSL hardware acceleration card called name. Available
212 only if OpenSSL-engine is installed on your system.
213 ECDHcurve "name"
215 Use the named curve for elliptical curve encryption (default:
216 prime256v1).
217 Control "/path/to/socket"
219 Set the control socket path. If not defined Pound does not lis‐
220 ten for any commands. The commands may be issued by using the
221 poundctl(8) program.
222 Include "/path/to/file"
224 Include the file as though it were part of the configuration
225 file.
226 Anonymise
228 Replace the last byte of the client address with 0 for logging
229 purposes. Default: log the client address in full.
230
232 An HTTP listener defines an address and port that Pound will listen on
233 for HTTP requests. All configuration directives enclosed between Lis‐
234 tenHTTP and End are specific to a single HTTP listener. At the very
235 least you must specify and address and a port for each listener. The
236 following directives are available:
237 Address address
239 The address that Pound will listen on. This can be a numeric IP
240 address, or a symbolic host name that must be resolvable at run-
241 time. This is a mandatory parameter. The address 0.0.0.0 may be
242 used as an alias for 'all available addresses on this machine',
243 but this practice is strongly discouraged, as it will interfere
244 with the rewriting mechanisms (see below).
245 Port port
247 The port number that Pound will listen on. This is a mandatory
248 parameter.
249 xHTTP value
251 Defines which HTTP verbs are accepted. The possible values are:
252 0 (default) accept only standard HTTP requests (GET, POST,
254 HEAD).
255 1 additionally allow extended HTTP requests (PUT, PATCH,
257 DELETE).
258 2 additionally allow standard WebDAV verbs (LOCK, UNLOCK,
260 PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE,
261 MKACTIVITY, CHECKOUT, MERGE, REPORT).
262 3 additionally allow MS extensions WebDAV verbs (SUBSCRIBE,
264 UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY,
265 BDELETE, CONNECT).
266 4 additionally allow MS RPC extensions verbs (RPC_IN_DATA,
268 RPC_OUT_DATA).
269 Client value
271 Override the global Client time-out value.
272 CheckURL "pattern to match"
274 Define a pattern that must be matched by each request sent to
275 this listener. A request that does not match is considered to be
276 illegal. By default Pound accepts all requests (i.e. the pat‐
277 tern is ".*"), but you are free to limit it to something more
278 reasonable. Please note that this applies only to the request
279 path - Pound will still check that the request is syntactically
280 correct.
281 Err414 "filename"
283 A file with the text to be displayed if an Error 414 occurs.
284 Default: "Request URI is too long.".
285 Err500 "filename"
287 A file with the text to be displayed if an Error 500 occurs.
288 Default: "An internal server error occurred. Please try again
289 later.".
290 Err501 "filename"
292 A file with the text to be displayed if an Error 501 occurs.
293 Default: "This method may not be used.".
294 Err503 "filename"
296 A file with the text to be displayed if an Error 503 occurs.
297 Default: "The service is not available. Please try again
298 later.".
299 MaxRequest nnn
301 Request maximal size. All requests will be limited to these many
302 bytes. If a request contains more data than allowed an error 414
303 is returned. Default: unlimited.
304 HeadRemove "header pattern"
306 Remove certain headers from the incoming requests. All
307 occurences of the matching specified header will be removed.
308 Please note that this filtering is done prior to other checks
309 (such as HeadRequire or HeadDeny), so you should not try to
310 check for these headers in later matches. Multiple directives
311 may be specified in order to remove more than one header, and
312 the header itself may be a regular pattern (though this should
313 be used with caution).
314 AddHeader "header: to add"
316 Add the defined header to the request passed to the back-end
317 server. The header is added verbatim. Use multiple AddHeader
318 directives if you need to add more than one header.
319 RewriteLocation 0|1|2
321 If 1 force Pound to change the Location: and Content-location:
322 headers in responses. If they point to the back-end itself or to
323 the listener (but with the wrong protocol) the response will be
324 changed to show the virtual host in the request. Default: 1
325 (active). If the value is set to 2 only the back-end address is
326 compared; this is useful for redirecting a request to an HTTPS
327 listener on the same server as the HTTP listener.
328 RewriteDestination 0|1
330 If 1 force Pound to change the Destination: header in requests.
331 The header is changed to point to the back-end itself with the
332 correct protocol. Default: 0.
333 LogLevel value
335 Override the global LogLevel value.
336 Service [ "name" ]
338 This defines a private service (see below for service definition
339 syntax). This service will be used only by this listener. The
340 service may be optionally named, with the name showing in the
341 poundctl listings.
342
344 An HTTPS listener defines an address and port that Pound will listen on
345 for HTTPS requests. All configuration directives enclosed between Lis‐
346 tenHTTPS and End are specific to a single HTTPS listener. At the very
347 least you must specify and address, a port and a server certificate for
348 each listener. All directives defined for HTTP listeners are applicable
349 to HTTPS listeners as well. The following additional directives are
350 also available:
351 Cert "certificate file"
353 Specify the server certificate. The certificate file is the file
354 containing the certificate, possibly a certificate chain and the
355 signature for this server. This directive is mandatory for HTTPS
356 listeners.
357 Please note that multiple Cert directives are allowed if your
359 OpenSSL version supports SNI. In such cases, the first directive
360 is the default certificate, with additional certificates used if
361 the client requests them.
362 The ordering of the directives is important: the first certifi‐
364 cate where the CN matches the client request will be used, so
365 put your directives in the most-specific-to-least specific order
366 (i.e. wildcard certificates after host-specific certificates).
367 Cert directives must precede all other SSL-specific directives.
369 ClientCert 0|1|2|3 depth
371 Ask for the client's HTTPS certificate: 0 - don't ask (default),
372 1 - ask, 2 - ask and fail if no certificate was presented, 3 -
373 ask but do not verify. Depth is the depth of verification for a
374 client certificate (up to 9). The default depth limit is 9,
375 allowing for the peer certificate and additional 9 CA certifi‐
376 cates that must be verified.
377 Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
379 Disable the protocol and all lower protocols as well. This is
380 due to a limitation in OpenSSL, which does not support disabling
381 a single protocol. For example, Disable TLSv1 would disable
382 SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
383 Ciphers "acceptable:cipher:list"
385 This is the list of ciphers that will be accepted by the SSL
386 connection; it is a string in the same format as in OpenSSL
387 ciphers(1) and SSL_CTX_set_cipher_list(3).
388 SSLHonorCipherOrder 0|1
390 If this value is 1, the server will broadcast a preference to
391 use Ciphers in the order supplied in the Ciphers directive. If
392 the value is 0, the server will treat the Ciphers list as the
393 list of Ciphers it will accept, but no preference will be indi‐
394 cated. Default value is 0.
395 SSLAllowClientRenegotiation 0|1|2
397 If this value is 0, client initiated renegotiation will be dis‐
398 abled. This will mitigate DoS exploits based on client renego‐
399 tiation, regardless of the patch status of clients and servers
400 related to "Secure renegotiation". If the value is 1, secure
401 renegotiation is supported. If the value is 2, insecure renego‐
402 tiation is supported, with unpatched clients. This can lead to a
403 DoS and a Man in the Middle attack! The default value is 0.
404 CAlist "CAcert_file"
406 Set the list of "trusted" CA's for this server. The CAcert_file
407 is a file containing a sequence of CA certificates (PEM format).
408 The names of the defined CA certificates will be sent to the
409 client on connection.
410 VerifyList "Verify_file"
412 Set the CA (Certificate Authority). The Verify_file is a file
413 that contains the CA root certificates (in PEM format).
414 Please note: there is an important difference between the CAlist
416 and the VerifyList. The CAlist tells the client (browser) which
417 client certificates it should send. The VerifyList defines which
418 CAs are actually used for the verification of the returned cer‐
419 tificate.
420 CRLlist "CRL_file"
422 Set the CRL (Certificate Revocation List) file. The CRL_file is
423 a file that contains the CRLs (in PEM format).
424 NoHTTPS11 0|1|2
426 Behave like an HTTP/1.0 server for HTTPS clients. If this value
427 is 0 disable the check. If the value is 1 do not allow multiple
428 requests on SSL connections. If the value is 2 (default) disable
429 multiple requests on SSL connections only for MSIE clients.
430 Required work-around for a bug in certain versions of IE.
431
433 A service is a definition of which back-end servers Pound will use to
434 reply to incoming requests. A service may be defined as part of a lis‐
435 tener (in which case it will be used only by that listener), or glob‐
436 ally (which makes it available to all listeners). Pound will always
437 try the private services in the order defined, followed by the global
438 ones.
439 All configuration directives enclosed between Service and End are spe‐
441 cific to a single service. The following directives are available:
442 URL "pattern"
444 Match the incoming request. If a request fails to match than
445 this service will be skipped and next one tried. If all services
446 fail to match Pound returns an error. You may define multiple
447 URL conditions per service, in which case all patterns must
448 match. If no URL was defined then all requests match. The match‐
449 ing is by default case-sensitive, but this can be overridden by
450 specifying IgnoreCase 1
451 IgnoreCase 0|1
453 Override the global IgnoreCase setting.
454 HeadRequire "pattern"
456 The request must contain at least on header matching the given
457 pattern. Multiple HeadRequire directives may be defined per
458 service, in which case all of them must be satisfied.
459 HeadDeny "pattern"
461 The request may not contain any header matching the given pat‐
462 tern. Multiple HeadDeny directives may be defined per service,
463 in which case all of them must be satisfied.
464 Please note: if the listener defined a HeadRemove directive, the
466 matching headers are removed before the service matching is
467 attempted.
468 DynScale 0|1
470 Enable or disable dynamic rescaling for the current service.
471 This value will override the value globally defined.
472 Disabled 0|1
474 Start Pound with this service disabled (1) or enabled (0). If
475 started as disabled, the service can be later enabled with
476 poundctl (8).
477 BackEnd
479 Directives enclosed between a BackEnd and the following End
480 directives define a single back-end server (see below for
481 details). You may define multiple back-ends per service, in
482 which case Pound will attempt to load-balance between them.
483 Redirect [code] "url"
485 This is a special type of back-end. Instead of sending the
486 request to a back-end Pound replies immediately with a redirect‐
487 ion to the given URL. You may define multiple redirectors in a
488 service, as well as mixing them with regular back-ends.
489 The address the client is redirected to is determined by the
491 actual url you specify: if it is a "pure" host (i.e. with no
492 path) then the client will be redirected to the host you speci‐
493 fied, with the original request path appended. If your url does
494 contain a path then the request path is ignored.
495 Examples: if you specified
497 Redirect "http://abc.example"
499 and the client requested http://xyz/a/b/c then it will be redi‐
501 rected to http://abc.example/a/b/c, but if you specified
502 Redirect "http://abc.example/index.html"
504 it will be sent to http://abc.example/index.html.
506 Technical note: in an ideal world Pound should reply with a "307
508 Temporary Redirect" status. Unfortunately, that is not yet sup‐
509 ported by all clients (in particular HTTP 1.0 ones), so Pound
510 currently replies by default with a "302 Found" instead. You may
511 override this behaviour by specifying the code to be used (301,
512 302 or 307).
513 Emergency
515 Directives enclosed between an Emergency and the following End
516 directives define an emergency back-end server (see below for
517 details). You may define only one emergency server per service,
518 which Pound will attempt to use if all backends are down.
519 Session
521 Directives enclosed between a Session and the following End
522 directives define a session-tracking mechanism for the current
523 service. See below for details.
524
526 A back-end is a definition of a single back-end server Pound will use
527 to reply to incoming requests. All configuration directives enclosed
528 between BackEnd and End are specific to a single service. The following
529 directives are available:
530 Address address
532 The address that Pound will connect to. This can be a numeric IP
533 address, or a symbolic host name that must be resolvable at run-
534 time. If the name cannot be resolved to a valid address, Pound
535 will assume that it represents the path for a Unix-domain
536 socket. This is a mandatory parameter.
537 Port port
539 The port number that Pound will connect to. This is a mandatory
540 parameter for non Unix-domain back-ends.
541 HTTPS The back-end is using HTTPS.
543 Cert "certificate file"
545 Specify the certificate that Pound will use as a client. The
546 certificate file is the file containing the certificate, possi‐
547 bly a certificate chain and the signature. This directive may
548 appear only after the HTTPS directive.
549 Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
551 Disable the protocol and all lower protocols as well. This is
552 due to a limitation in OpenSSL, which does not support disabling
553 a single protocol. For example, Disable TLSv1 would disable
554 SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
555 This directive may appear only after the HTTPS directive.
556 Ciphers "acceptable:cipher:list"
558 This is the list of ciphers that will be accepted by the SSL
559 connection; it is a string in the same format as in OpenSSL
560 ciphers(1) and SSL_CTX_set_cipher_list(3). This directive may
561 appear only after the HTTPS directive.
562 Priority val
564 The priority of this back-end (between 1 and 9, 5 is default).
565 Higher priority back-ends will be used more often than lower
566 priority ones, so you should define higher priorities for more
567 capable servers.
568 TimeOut val
570 Override the global TimeOut value.
571 ConnTO val
573 Override the global ConnTO value.
574 HAport [ address ] port
576 A port (and optional address) to be used for server function
577 checks. See below the "High Availability" section for a more
578 detailed discussion. By default Pound uses the same address as
579 the back-end server, but you may use a separate address if you
580 wish. This directive applies only to non Unix-domain servers.
581 Disabled 0|1
583 Start Pound with this back-end disabled (1) or enabled (0). If
584 started as disabled, the back-end can be later enabled with
585 poundctl (8).
586
588 The emergency server will be used once all existing back-ends are
589 "dead". All configuration directives enclosed between Emergency and
590 End are specific to a single service. The following directives are
591 available:
592 Address address
594 The address that Pound will connect to. This can be a numeric IP
595 address, or a symbolic host name that must be resolvable at run-
596 time. If the name cannot be resolved to a valid address, Pound
597 will assume that it represents the path for a Unix-domain
598 socket. This is a mandatory parameter.
599 Port port
601 The port number that Pound will connect to. This is a mandatory
602 parameter for non Unix-domain back-ends.
603
605 Defines how a service deals with possible HTTP sessions. All configu‐
606 ration directives enclosed between Session and End are specific to a
607 single service. Once a sessions is identified, Pound will attempt to
608 send all requests within that session to the same back-end server.
609 The following directives are available:
611 Type IP|BASIC|URL|PARM|COOKIE|HEADER
613 What kind of sessions are we looking for: IP (the client
614 address), BASIC (basic authentication), URL (a request parame‐
615 ter), PARM (a URI parameter), COOKIE (a certain cookie), or
616 HEADER (a certain request header). This is a mandatory parame‐
617 ter.
618 TTL seconds
620 How long can a session be idle (in seconds). A session that has
621 been idle for longer than the specified number of seconds will
622 be discarded. This is a mandatory parameter.
623 ID "name"
625 The session identifier. This directive is permitted only for
626 sessions of type URL (the name of the request parameter we need
627 to track), COOKIE (the name of the cookie) and HEADER (the
628 header name).
629 See below for some examples.
631
633 Pound attempts to keep track of active back-end servers, and will tem‐
634 porarily disable servers that do not respond (though not necessarily
635 dead: an overloaded server that Pound cannot establish a connection to
636 will be considered dead). However, every Alive seconds, an attempt is
637 made to connect to the dead servers in case they have become active
638 again. If this attempt succeeds, connections will be initiated to them
639 again.
640 In general it is a good idea to set this time interval as low as is
642 consistent with your resources in order to benefit from resurected
643 servers at the earliest possible time. The default value of 30 seconds
644 is probably a good choice.
645 The clients that happen upon a dead backend server will just receive a
647 503 Service Unavailable message.
648 The HAport parameter specifies an additional port (and optionally an
650 address) that is used only for viability checks: if this port is speci‐
651 fied in a BackEnd directive, Pound will attempt periodically (every
652 Alive seconds) to connect to this port. If the port does not respond
653 the server is considered dead. It never makes sense to have the HAport
654 identical to the main back-end port: this would only generate extra,
655 unncecessary activity (CPU, network traffic) for no good reason whatso‐
656 ever. The HAport is meant for applications that offer an additional
657 health monitoring port or for installations that wish to take servers
658 off-line in a controlled manner.
659 By default the address of the HAport health monitor is the same as that
661 of the back-end server. You may specify a different address though, for
662 example if you have a monitoring program running on another host.
663
665 If a client browser connects to Pound via HTTPS and if it presents a
666 client certificate Pound adds the following headers to the request it
667 issues to the server:
668 X-SSL-Subject
670 Details about the certificate owner.
671 X-SSL-Issuer
673 Details about the certificate issuer (Certificate Authority).
674 X-SSL-notBefore
676 Starting date of certificate validity.
677 X-SSL-notAfter
679 Ending date of certificate validity.
680 X-SSL-serial
682 Certificate serial number (decimal).
683 X-SSL-cipher
685 The cipher currently in use.
686 X-SSL-certificate
688 The full client certificate (PEM-format multi-line)
689 It is the application's responsibility to actually use these headers -
691 Pound just passes this information without checking it in any way
692 (except for signature and encryption correctness).
693
695 In general, Pound does not read or write to the hard-disk. The excep‐
696 tions are reading the configuration file and (possibly) the server cer‐
697 tificate file(s) and error message(s), which are opened read-only on
698 startup, read, and closed, and the pid file which is opened on start-
699 up, written to and immediately closed. Following this there is no disk
700 access whatsoever, so using a RootJail directive is only for extra
701 security bonus points.
702 Pound tries to sanitise all HTTP/HTTPS requests: the request itself,
704 the headers and the contents are checked for conformance to the RFC's
705 and only valid requests are passed to the back-end servers. This is not
706 absolutely fool-proof - as the recent Apache problem with chunked
707 transfers demonstrated. However, given the current standards, this is
708 the best that can be done - HTTP is an inherently weak protocol.
709
711 Pound uses the system log for messages (default facility LOG_DAEMON).
712 The format is very similar to other web servers, so that if you want to
713 use a log tool:
714 fgrep pound /var/log/messages | your_log_tool
716 Translating HTTPS to HTTP is an iffy proposition: no client information
718 is passed to the server itself (certificates, etc) and the backend
719 server may be misled if it uses absolute URLs. A patch for Zope is
720 included in the distribution to address this issue - for other Web
721 servers you are on your own. May the source be with you.
722 Pound deals with (and sanitizes) HTTP/1.1 requests. Thus even if you
724 have an HTTP/1.0 server, a single connection to an HTTP/1.1 client is
725 kept, while the connection to the back-end server is re-opened as nec‐
726 essary.
727 Pound attempts to resolve the names of the hosts that appear in various
729 requests and/or responses. That means it need a functioning resolver
730 of some kind (be it /etc/hosts, DNS or something else).
731
733 To translate HTTPS requests to a local HTTP server (assuming your net‐
734 work address is 123.123.123.123):
735 ListenHTTPS
737 Address 1.2.3.4
738 Port 443
739 Cert "/etc/pound/server.pem"
740 Service
742 BackEnd
743 Address 127.0.0.1
744 Port 80
745 End
746 End
747 End
748 To distribute the HTTP/HTTPS requests to three Web servers, where the
750 third one is a newer and faster machine:
751 ListenHTTP
753 Address 123.123.123.123
754 Port 80
755 End
756 ListenHTTPS
757 Address 1.2.3.4
758 Port 443
759 Cert "/etc/pound/server.pem"
760 End
761 Service
763 BackEnd
764 Address 192.168.0.10
765 Port 80
766 End
767 BackEnd
768 Address 192.168.0.11
769 Port 80
770 End
771 BackEnd
772 Address 192.168.0.12
773 Port 80
774 Priority 3
775 End
776 End
777 To separate between image requests and other Web content and send all
779 requests for a specific URL to a secure server:
780 ListenHTTP
782 Address 123.123.123.123
783 Port 80
784 End
785 # Images server(s)
787 Service
788 URL ".*.(jpg|gif)"
789 BackEnd
790 Address 192.168.0.12
791 Port 80
792 End
793 End
794 # redirect all requests for /forbidden
796 Service
797 Url "/forbidden.*"
798 Redirect "https://xyzzy.com"
799 End
800 # Catch-all server(s)
802 Service
803 BackEnd
804 Address 192.168.0.10
805 Port 80
806 End
807 BackEnd
808 Address 192.168.0.11
809 Port 80
810 End
811 Session
812 Type BASIC
813 TTL 300
814 End
815 End
816 Here is a more complex example: assume your static images (GIF/JPEG)
818 are to be served from a single back-end 192.168.0.10. In addition,
819 192.168.0.11 is to do the hosting for www.myserver.com with URL-based
820 sessions, and 192.168.0.20 (a 1GHz PIII) and 192.168.0.21 (800Mhz
821 Duron) are for all other requests (cookie-based sessions). The logging
822 will be done by the back-end servers. The configuration file may look
823 like this:
824 User "nobody"
826 Group "nogroup"
827 RootJail "/var/pound/jail"
828 Alive 60
829 LogLevel 0
830 # Main listening ports
832 ListenHTTP
833 Address 1.2.3.4
834 Port 80
835 Client 10
836 End
837 ListenHTTPS
838 Address 1.2.3.4
839 Port 443
840 Cert "/etc/pound/pound.pem"
841 Client 20
842 End
843 # Image server
845 Service
846 URL ".*.(jpg|gif)"
847 BackEnd
848 Address 192.168.0.10
849 Port 80
850 End
851 End
852 # Virtual host www.myserver.com
854 Service
855 URL ".*sessid=.*"
856 HeadRequire "Host:.*www.myserver.com.*"
857 BackEnd
858 Address 192.168.0.11
859 Port 80
860 End
861 Session
862 Type URL
863 ID "sessid"
864 TTL 120
865 End
866 End
867 # Everybody else
869 Service
870 BackEnd
871 Address 192.168.0.20
872 Port 80
873 Priority 5
874 End
875 BackEnd
876 Address 192.168.0.21
877 Port 80
878 Priority 4
879 End
880 Session
881 Type COOKIE
882 ID "userid"
883 TTL 180
884 End
885 End
886
888 /var/run/pound.nnn
889 this is where Pound will attempt to record its process id.
890 /usr/local/etc/pound.cfg
892 the default configuration file (the location may be changed when
893 compiling - see the F_CONF flag in the Makefile).
894 /usr/local/etc/pound/cert.pem
896 the certificate file(s) for HTTPS. The location must be defined
897 in the configuration file - this is only a suggestion. The file
898 must contain a PEM-encoded certificate, optionally a certificate
899 chain from a known Certificate Authority to your server certifi‐
900 cate and a PEM-encoded private key (not password protected). See
901 OpenSSL(1) for details. This file should be well protected, lest
902 someone gets your server private key.
903
905 Written by Robert Segall, Apsis GmbH.
906
908 Report bugs to <roseg@apsis.ch>.
909
911 Copyright © 2002-2010 Apsis GmbH.
912 This is free software; see the source for copying conditions. There is
913 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
914 PURPOSE.
915pound Jan 2010 POUND(8)