1POUND(8)                    System Manager's Manual                   POUND(8)
2
3
4

NAME

6       pound - HTTP/HTTPS reverse-proxy and load-balancer
7

SYNOPSIS

9       pound  [-v] [-c] [-V] [-f config_file] [-p pid_file]
10

DESCRIPTION

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
17       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

GENERAL PRINCIPLES

22       In general Pound needs three types of objects defined in order to func‐
23       tion: listeners, services and back-ends.
24
25       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
32       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
46       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
52              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
59              Multiple back-ends may be defined within  a  service,  in  which
60              case Pound will load-balance between the available back-ends.
61
62              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
70              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

OPTIONS

75       Options available (see also below for configuration file options):
76
77       -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
82       -V     Print version: Pound will exit immediately  after  printing  the
83              current version and configuration flags.
84
85       -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
89       -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
93       -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
99       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
103       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

CONFIGURATION FILE

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

GLOBAL DIRECTIVES

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
121       User "user_name"
122              Specify  the  user  Pound  will  run  as  (must  be  defined  in
123              /etc/passwd).
124
125       Group "group_name"
126              Specify the  group  Pound  will  run  as  (must  be  defined  in
127              /etc/group).
128
129       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
136       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
144       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
152       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
158       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
167       IgnoreCase 0|1
168              Ignore case when matching URLs (default: 0). This value  can  be
169              overridden for specific services.
170
171       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
177       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
184       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
193       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
198       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
203       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
210       SSLEngine "name"
211              Use an OpenSSL hardware acceleration card called name. Available
212              only if OpenSSL-engine is installed on your system.
213
214       ECDHcurve "name"
215              Use  the  named  curve for elliptical curve encryption (default:
216              prime256v1).
217
218       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
223       Include "/path/to/file"
224              Include the file as though it were  part  of  the  configuration
225              file.
226
227       Anonymise
228              Replace  the  last byte of the client address with 0 for logging
229              purposes.  Default: log the client address in full.
230

HTTP Listener

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
238       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
246       Port port
247              The  port number that Pound will listen on.  This is a mandatory
248              parameter.
249
250       xHTTP value
251              Defines which HTTP verbs are accepted. The possible values are:
252
253              0 (default) accept  only  standard  HTTP  requests  (GET,  POST,
254              HEAD).
255
256              1   additionally  allow  extended  HTTP  requests  (PUT,  PATCH,
257              DELETE).
258
259              2  additionally  allow  standard  WebDAV  verbs  (LOCK,  UNLOCK,
260              PROPFIND,  PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE,
261              MKACTIVITY, CHECKOUT, MERGE, REPORT).
262
263              3 additionally allow  MS  extensions  WebDAV  verbs  (SUBSCRIBE,
264              UNSUBSCRIBE,  NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY,
265              BDELETE, CONNECT).
266
267              4 additionally  allow  MS  RPC  extensions  verbs  (RPC_IN_DATA,
268              RPC_OUT_DATA).
269
270       Client value
271              Override the global Client time-out value.
272
273       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
282       Err414 "filename"
283              A  file  with  the  text to be displayed if an Error 414 occurs.
284              Default: "Request URI is too long.".
285
286       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
291       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
295       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
300       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
305       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
315       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
320       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
329       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
334       LogLevel value
335              Override the global LogLevel value.
336
337       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

HTTPS Listener

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
352       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
358              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
363              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
368              Cert directives must precede all other SSL-specific directives.
369
370       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
378       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
384       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
389       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
396       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
405       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
411       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
415              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
421       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
425       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

Service

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
440       All configuration directives enclosed between Service and End are  spe‐
441       cific to a single service. The following directives are available:
442
443       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
452       IgnoreCase 0|1
453              Override the global IgnoreCase setting.
454
455       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
460       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
465              Please note: if the listener defined a HeadRemove directive, the
466              matching headers are removed  before  the  service  matching  is
467              attempted.
468
469       DynScale 0|1
470              Enable  or  disable  dynamic  rescaling for the current service.
471              This value will override the value globally defined.
472
473       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
478       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
484       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
490              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
496              Examples: if you specified
497
498                  Redirect "http://abc.example"
499
500              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
503                  Redirect "http://abc.example/index.html"
504
505              it will be sent to http://abc.example/index.html.
506
507              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
514       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
520       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

BackEnd

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
531       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
538       Port port
539              The port number that Pound will connect to. This is a  mandatory
540              parameter for non Unix-domain back-ends.
541
542       HTTPS  The back-end is using HTTPS.
543
544       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
550       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
557       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
563       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
569       TimeOut val
570              Override the global TimeOut value.
571
572       ConnTO val
573              Override the global ConnTO value.
574
575       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
582       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

Emergency

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
593       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
600       Port port
601              The  port number that Pound will connect to. This is a mandatory
602              parameter for non Unix-domain back-ends.
603

Session

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
610       The following directives are available:
611
612       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
619       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
624       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
630       See below for some examples.
631

HIGH-AVAILABILITY

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
641       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
646       The  clients that happen upon a dead backend server will just receive a
647       503 Service Unavailable message.
648
649       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
660       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

HTTPS HEADERS

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
669       X-SSL-Subject
670              Details about the certificate owner.
671
672       X-SSL-Issuer
673              Details about the certificate issuer (Certificate Authority).
674
675       X-SSL-notBefore
676              Starting date of certificate validity.
677
678       X-SSL-notAfter
679              Ending date of certificate validity.
680
681       X-SSL-serial
682              Certificate serial number (decimal).
683
684       X-SSL-cipher
685              The cipher currently in use.
686
687       X-SSL-certificate
688              The full client certificate (PEM-format multi-line)
689
690       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

SECURITY

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
703       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

ADDITIONAL NOTES

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
715           fgrep pound /var/log/messages | your_log_tool
716
717       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
723       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
728       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

EXAMPLES

733       To  translate HTTPS requests to a local HTTP server (assuming your net‐
734       work address is 123.123.123.123):
735
736              ListenHTTPS
737                  Address 1.2.3.4
738                  Port    443
739                  Cert    "/etc/pound/server.pem"
740
741                  Service
742                      BackEnd
743                          Address 127.0.0.1
744                          Port    80
745                      End
746                  End
747              End
748
749       To distribute the HTTP/HTTPS requests to three Web servers,  where  the
750       third one is a newer and faster machine:
751
752              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
762              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
778       To  separate  between image requests and other Web content and send all
779       requests for a specific URL to a secure server:
780
781              ListenHTTP
782                  Address 123.123.123.123
783                  Port    80
784              End
785
786              # 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
795              # redirect all requests for /forbidden
796              Service
797                  Url         "/forbidden.*"
798                  Redirect    "https://xyzzy.com"
799              End
800
801              # 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
817       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
825              User        "nobody"
826              Group       "nogroup"
827              RootJail    "/var/pound/jail"
828              Alive       60
829              LogLevel    0
830
831              # 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
844              # Image server
845              Service
846                  URL ".*.(jpg|gif)"
847                  BackEnd
848                      Address 192.168.0.10
849                      Port    80
850                  End
851              End
852
853              # 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
868              # 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

FILES

888       /var/run/pound.nnn
889              this is where Pound will attempt to record its process id.
890
891       /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
895       /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

AUTHOR

905       Written by Robert Segall, Apsis GmbH.
906

REPORTING BUGS

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.
915
916
917
918pound                              Jan 2010                           POUND(8)
Impressum