Provided by: pound_2.6-3_amd64 bug

NAME

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

SYNOPSIS

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

DESCRIPTION

       Pound  is  a  reverse-proxy  load  balancing  server.  It accepts requests from HTTP/HTTPS
       clients and distributes them to one or more Web servers. The HTTPS requests are  decrypted
       and passed to the back-ends as plain HTTP.

       If  more than one back-end server is defined, Pound chooses one of them randomly, based on
       defined priorities. By default, Pound keeps track  of  associations  between  clients  and
       back-end servers (sessions).

GENERAL PRINCIPLES

       In  general  Pound  needs  three types of objects defined in order to function: listeners,
       services and back-ends.

       Listeners
              A listener is a  definition  of  how  Pound  receives  requests  from  the  clients
              (browsers). Two types of listeners may be defined: regular HTTP listeners and HTTPS
              (HTTP over SSL/TLS) listeners.  At the  very  least  a  listener  must  define  the
              address and port to listen on, with additional requirements for HTTPS listeners.

       Services
              A  service  is the definition of how the requests are answered. The services may be
              defined within a listener or at the top level (global). When a request is  received
              Pound  attempts  to  match them to each service in turn, starting with the services
              defined in the listener itself and, if needed, continuing with the services defined
              at  the  global  level.  The  services  may define their own conditions as to which
              requests they can answer: typically this involves certain URLs (images only,  or  a
              certain  path)  or  specific  headers (such as the Host header). A service may also
              define a session mechanism: if defined future requests from  a  given  client  will
              always be answered by the same back-end.

       Back-ends
              The  back-ends  are  the actual servers for the content requested. By itself, Pound
              supplies no responses - all contents must be received from a "real" web server. The
              back-end defines how the server should be contacted.

              Three  types  of  back-ends  may  be  defined:  a "regular" back-end which receives
              requests and returns responses, a "redirect" back-end  in  which  case  Pound  will
              respond  with  a  redirect  response,  without accessing any back-end at all, or an
              "emergency" back-end which will be used only if all other backends are "dead".

              Multiple back-ends may be defined within a service, in which case Pound will  load-
              balance between the available back-ends.

              If  a  back-end  fails to respond it will be considered "dead", in which case Pound
              will stop sending requests to it.  Dead  back-ends  are  periodically  checked  for
              availability,  and  once  they respond again they are "resurected" and requests are
              sent again their way. If no back-ends are available (none were defined, or all  are
              "dead")  then  Pound  will  reply  with "503 Service Unavailable", without checking
              additional services.

              The connection between Pound and the back-ends is always via  HTTP,  regardless  of
              the actual protocol used between Pound and the client.

OPTIONS

       Options available (see also below for configuration file options):

       -v     Verbose mode: error messages will be sent to stdout even if Pound was configured to
              log to syslog. This applies only to startup messages, before Pound puts  itself  in
              the background. Normal operational messages will still go to syslog.

       -V     Print  version:  Pound will exit immediately after printing the current version and
              configuration flags.

       -c     Check only: Pound will exit immediately after parsing the configuration file.  This
              may be used for running a quick syntax check before actually activating a server.

       -f config_file
              Location  of  the  configuration  file  (see  below  for  a full description of the
              format).  Default: /usr/local/etc/pound.cfg

       -p pid_file
              Location of the pid file.  Pound will write its own pid into  this  file.  Normally
              this  is  used  for shell scripts that control starting and stopping of the daemon.
              Default: /var/run/pound.pid

       In general, any number of back-end servers may be specified. Use the  priority  to  affect
       the load distribution among unequal-performance servers.

       One (or more) copies of Pound should be started at boot time. Use "big iron" if you expect
       heavy loads: while Pound is as light-weight as I know how  to  make  it,  with  a  lot  of
       simultaneous  requests  it  will use quite a bit of CPU and memory. Multiple CPUs are your
       friend.

CONFIGURATION FILE

       Each line in the file is considered a complete configuration directive. The directives are
       case-insensitive.  Empty lines or lines starting in '#' are ignored. There are three types
       of directives: global  directives  (they  affect  the  settings  for  the  entire  program
       instance),  listener  directives  (they  define which requests Pound will listen for), and
       service directives (they affect only a specific group of requests).

GLOBAL DIRECTIVES

       Global directives may  appear  anywhere  within  the  configuration  file,  though  it  is
       customary for them to be at the start. They may appear in any order.

       User "user_name"
              Specify the user Pound will run as (must be defined in /etc/passwd).

       Group "group_name"
              Specify the group Pound will run as (must be defined in /etc/group).

       RootJail "directory_path_and_name"
              Specify  the  directory  that  Pound  will  chroot  to at runtime. Please note that
              OpenSSL requires access to /dev/urandom, so make sure you create a device  by  that
              name,  accessible  from  the root jail directory.  Pound may also require access to
              /dev/syslog or similar.

       Daemon 0|1
              Have Pound run in the foreground (if 0) or as a daemon (if  1).  By  default  Pound
              runs  as a daemon (detaches itself from the controlling terminal and puts itself in
              the background). By specifying this option you can  force  Pound  to  work  like  a
              regular  process.  Useful  for  debugging  or  if  you  want  to use something like
              daemontools.

       Threads nnn
              How many worker threads Pound should use. Default:  128.  Tune  this  parameter  to
              improve performance.  If you set it too high, Pound will use a lot memory, and some
              CPU will be wasted on context switches.  If you set it  too  low  requests  may  be
              served with some delay. Experiment to find the optimal value for your installation.

       LogFacility value
              Specify  the  log  facility  to  use.   value  (default: daemon) must be one of the
              symbolic facility names defined in  syslog.h.  This  facility  shall  be  used  for
              logging. Using a - for the facility name causes Pound to log to stdout/stderr.

       LogLevel value
              Specify the logging level: 0 for no logging, 1 (default) for regular logging, 2 for
              extended logging (show chosen backend server as well),  3  for  Apache-like  format
              (Combined  Log Format with Virtual Host), 4 (same as 3 but without the virtual host
              information) and 5 (same as 4 but with information about the  Service  and  BackEnd
              used).  This value can be overridden for specific listeners.

       IgnoreCase 0|1
              Ignore  case  when  matching  URLs  (default:  0). This value can be overridden for
              specific services.

       DynScale 0|1
              Enable or disable the dynamic rescaling code (default: 0). If  enabled  Pound  will
              periodically  try  to  modify  the  back-end  priorities  in  order to equalise the
              response times from the various  back-ends.   This  value  can  be  overridden  for
              specific services.

       Alive value
              Specify  how  often  Pound  will  check  for resurected back-end hosts (default: 30
              seconds). In general, it is a good idea to set this as low as possible  -  it  will
              find  resurected  hosts  faster.  However,  if  you  set it too low it will consume
              resources - so beware.

       Client value
              Specify for how long Pound will wait for a client request  (default:  10  seconds).
              After this long has passed without the client sending any data Pound will close the
              connection. Set it higher if your clients time-out on a slow network or over-loaded
              server,  lower  if  you  start  getting  DOS  attacks  or run into problems with IE
              clients.  This value can be overridden for specific listeners.

       TimeOut value
              How long should Pound wait for a response from the back-end (in seconds).  Default:
              15 seconds.  This value can be overridden for specific back-ends.

       ConnTO value
              How  long should Pound wait for a connection to the back-end (in seconds). Default:
              the TimeOut value. This value can be overridden for specific back-ends.

       Grace value
              How long should Pound continue to answer existing connections after a receiving and
              INT  or  HUP  signal  (default:  30  seconds).  The configured listeners are closed
              immediately. You can bypass this behaviour by stopping Pound with a  TERM  or  QUIT
              signal, in which case the program exits without any delay.

       SSLEngine "name"
              Use  an  OpenSSL hardware acceleration card called name. Available only if OpenSSL-
              engine is installed on your system.

       Control "/path/to/socket"
              Set the control socket path. If not defined Pound does not listen for any commands.
              The commands may be issued by using the poundctl(8) program.

       Include "/path/to/file"
              Include the file as though it were part of the configuration file.

HTTP Listener

       An  HTTP listener defines an address and port that Pound will listen on for HTTP requests.
       All configuration directives enclosed between ListenHTTP and End are specific to a  single
       HTTP  listener.  At  the  very  least  you  must  specify  and address and a port for each
       listener. The following directives are available:

       Address address
              The address that Pound will listen on. This can be  a  numeric  IP  address,  or  a
              symbolic  host  name  that  must  be  resolvable  at run-time.  This is a mandatory
              parameter. The address 0.0.0.0 may be used as an alias for 'all available addresses
              on  this  machine', but this practice is strongly discouraged, as it will interfere
              with the rewriting mechanisms (see below).

       Port port
              The port number that Pound will listen on.  This is a mandatory parameter.

       xHTTP value
              Defines which HTTP verbs are accepted. The possible values are:

              0 (default) accept only standard HTTP requests (GET, POST, HEAD).

              1 additionally allow extended HTTP requests (PUT, DELETE).

              2 additionally allow standard WebDAV  verbs  (LOCK,  UNLOCK,  PROPFIND,  PROPPATCH,
              SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY, CHECKOUT, MERGE, REPORT).

              3  additionally  allow  MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE, NOTIFY,
              BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).

              4 additionally allow MS RPC extensions verbs (RPC_IN_DATA, RPC_OUT_DATA).

       Client value
              Override the global Client time-out value.

       CheckURL "pattern to match"
              Define a pattern that must be matched by each request  sent  to  this  listener.  A
              request  that does not match is considered to be illegal.  By default Pound accepts
              all requests (i.e. the pattern is ".*"), but you are free to limit it to  something
              more  reasonable.  Please  note  that this applies only to the request path - Pound
              will still check that the request is syntactically correct.

       Err414 "filename"
              A file with the text to be displayed if an Error 414 occurs.  Default: "Request URI
              is too long.".

       Err500 "filename"
              A file with the text to be displayed if an Error 500 occurs.  Default: "An internal
              server error occurred. Please try again later.".

       Err501 "filename"
              A file with the text to be displayed if an Error 501 occurs.  Default: "This method
              may not be used.".

       Err503 "filename"
              A file with the text to be displayed if an Error 503 occurs.  Default: "The service
              is not available. Please try again later.".

       MaxRequest nnn
              Request maximal size. All requests will be  limited  to  these  many  bytes.  If  a
              request  contains  more  data  than  allowed  an  error  414  is returned. Default:
              unlimited.

       HeadRemove "header pattern"
              Remove certain headers from the incoming requests. All occurences of  the  matching
              specified  header will be removed. Please note that this filtering is done prior to
              other checks (such as HeadRequire or HeadDeny), so you should not try to check  for
              these  headers  in  later matches. Multiple directives may be specified in order to
              remove more than one header, and the header itself may be a regular pattern (though
              this should be used with caution).

       AddHeader "header: to add"
              Add  the defined header to the request passed to the back-end server. The header is
              added verbatim. Use multiple AddHeader directives if you need to add more than  one
              header.

       RewriteLocation 0|1|2
              If  1  force  Pound  to  change  the  Location:  and  Content-location:  headers in
              responses. If they point to the back-end itself or to the listener  (but  with  the
              wrong  protocol)  the  response  will  be  changed  to show the virtual host in the
              request. Default: 1 (active).  If the value is set to 2 only the  back-end  address
              is  compared;  this is useful for redirecting a request to an HTTPS listener on the
              same server as the HTTP listener.

       RewriteDestination 0|1
              If 1 force Pound to change the Destination:  header  in  requests.  The  header  is
              changed to point to the back-end itself with the correct protocol. Default: 0.

       LogLevel value
              Override the global LogLevel value.

       Service [ "name" ]
              This  defines  a  private  service  (see below for service definition syntax). This
              service will be used only by this listener. The service may  be  optionally  named,
              with the name showing in the poundctl listings.

HTTPS Listener

       An  HTTPS  listener  defines  an  address  and  port  that  Pound will listen on for HTTPS
       requests. All configuration directives enclosed between ListenHTTPS and End  are  specific
       to  a  single HTTPS listener. At the very least you must specify and address, a port and a
       server certificate for each listener.  All  directives  defined  for  HTTP  listeners  are
       applicable  to  HTTPS  listeners  as  well.  The  following additional directives are also
       available:

       Cert "certificate file"
              Specify the server certificate. The certificate file is  the  file  containing  the
              certificate,  possibly  a certificate chain and the signature for this server. This
              directive is mandatory for HTTPS listeners.

              Please note that multiple Cert directives  are  allowed  if  your  OpenSSL  version
              supports  SNI.  In such cases, the first directive is the default certificate, with
              additional certificates used if the client requests them.

              The ordering of the directives is important: the first  certificate  where  the  CN
              matches  the  client  request  will  be  used,  so put your directives in the most-
              specific-to-least specific order (i.e. wildcard  certificates  after  host-specific
              certificates).

              Cert directives must precede all other SSL-specific directives.

       ClientCert 0|1|2|3 depth
              Ask  for  the client's HTTPS certificate: 0 - don't ask (default), 1 - ask, 2 - ask
              and fail if no certificate was presented, 3 - ask but do not verify.  Depth is  the
              depth  of  verification for a client certificate (up to 9). The default depth limit
              is 9, allowing for the peer certificate and additional 9 CA certificates that  must
              be verified.

       Ciphers "acceptable:cipher:list"
              This  is  the  list of ciphers that will be accepted by the SSL connection; it is a
              string in the same format as in OpenSSL ciphers(1) and SSL_CTX_set_cipher_list(3).

       SSLHonorCipherOrder 0|1
              If this value is 1, the server will broadcast a preference to use  Ciphers  in  the
              order  supplied in the Ciphers directive.  If the value is 0, the server will treat
              the Ciphers list as the list of Ciphers it will accept, but no preference  will  be
              indicated.  Default value is 0.

       SSLAllowClientRenegotiation 0|1|2
              If  this  value  is  0, client initiated renegotiation will be disabled.  This will
              mitigate DoS exploits based on client renegotiation, regardless of the patch status
              of  clients  and  servers  related  to  "Secure renegotiation".  If the value is 1,
              secure renegotiation is supported.  If the value is 2,  insecure  renegotiation  is
              supported,  with  unpatched  clients.   /fBThis  can lead to a DoS and a Man in the
              Middle attack!/fR  Default value is 0.

       CAlist "CAcert_file"
              Set the list of  "trusted"  CA's  for  this  server.  The  CAcert_file  is  a  file
              containing  a sequence of CA certificates (PEM format). The names of the defined CA
              certificates will be sent to the client on connection.

       VerifyList "Verify_file"
              Set the CA (Certificate Authority). The Verify_file is a file that contains the  CA
              root certificates (in PEM format).

              Please  note:  there  is  an  important  difference  between  the  CAlist  and  the
              VerifyList. The CAlist tells the client  (browser)  which  client  certificates  it
              should   send.  The  VerifyList  defines  which  CAs  are  actually  used  for  the
              verification of the returned certificate.

       CRLlist "CRL_file"
              Set the CRL (Certificate Revocation  List)  file.  The  CRL_file  is  a  file  that
              contains the CRLs (in PEM format).

       NoHTTPS11 0|1|2
              Behave  like  an  HTTP/1.0 server for HTTPS clients. If this value is 0 disable the
              check. If the value is 1 do not allow multiple requests on SSL connections. If  the
              value  is  2  (default)  disable multiple requests on SSL connections only for MSIE
              clients. Required work-around for a bug in certain versions of IE.

Service

       A service is a definition of which back-end servers Pound will use to  reply  to  incoming
       requests.  A  service  may be defined as part of a listener (in which case it will be used
       only by that listener), or globally (which makes it available to  all  listeners).   Pound
       will always try the private services in the order defined, followed by the global ones.

       All  configuration  directives  enclosed  between Service and End are specific to a single
       service. The following directives are available:

       URL "pattern"
              Match the incoming request. If a request fails to match than this service  will  be
              skipped  and  next one tried. If all services fail to match Pound returns an error.
              You may define multiple URL conditions per service. If no URL was defined then  all
              requests  match.  The  matching  is  by  default  case-sensitive,  but  this can be
              overridden by specifying IgnoreCase 1

       IgnoreCase 0|1
              Override the global IgnoreCase setting.

       HeadRequire "pattern"
              The request must contain at least on header matching the given  pattern.   Multiple
              HeadRequire  directives  may be defined per service, in which case all of them must
              be satisfied.

       HeadDeny "pattern"
              The request may not contain  any  header  matching  the  given  pattern.   Multiple
              HeadDeny  directives  may be defined per service, in which case all of them must be
              satisfied.

              Please note: if the listener defined a HeadRemove directive, the  matching  headers
              are removed before the service matching is attempted.

       DynScale 0|1
              Enable  or  disable  dynamic  rescaling  for  the  current service. This value will
              override the value globally defined.

       Disabled 0|1
              Start Pound with this service disabled (1) or enabled (0). If started as  disabled,
              the service can be later enabled with poundctl (8).

       BackEnd
              Directives  enclosed  between  a  BackEnd and the following End directives define a
              single back-end server (see below for details). You may define  multiple  back-ends
              per service, in which case Pound will attempt to load-balance between them.

       Redirect [code] "url"
              This  is  a  special type of back-end. Instead of sending the request to a back-end
              Pound replies immediately with a redirection to  the  given  URL.  You  may  define
              multiple redirectors in a service, as well as mixing them with regular back-ends.

              The  address  the  client  is  redirected  to  is  determined by the actual url you
              specify: if it is a "pure" host (i.e.  with  no  path)  then  the  client  will  be
              redirected  to  the host you specified, with the original request path appended. If
              your url does contain a path then the request path is ignored.

              Examples: if you specified

                  Redirect "http://abc.example"

              and  the  client  requested  http://xyz/a/b/c  then  it  will  be   redirected   to
              http://abc.example/a/b/c, but if you specified

                  Redirect "http://abc.example/index.html"

              it will be sent to http://abc.example/index.html.

              Technical  note:  in  an  ideal  world  Pound  should  reply  with a "307 Temporary
              Redirect" status. Unfortunately, that is not  yet  supported  by  all  clients  (in
              particular HTTP 1.0 ones), so Pound currently replies by default with a "302 Found"
              instead. You may override this behaviour by specifying the code to  be  used  (301,
              302 or 307).

       Emergency
              Directives enclosed between an Emergency and the following End directives define an
              emergency back-end server  (see  below  for  details).  You  may  define  only  one
              emergency  server  per service, which Pound will attempt to use if all backends are
              down.

       Session
              Directives enclosed between a Session and the following  End  directives  define  a
              session-tracking mechanism for the current service. See below for details.

BackEnd

       A back-end is a definition of a single back-end server Pound will use to reply to incoming
       requests.  All configuration directives enclosed between BackEnd and End are specific to a
       single service. The following directives are available:

       Address address
              The  address  that  Pound  will  connect to. This can be a numeric IP address, or a
              symbolic host name that must be resolvable at  run-time.  If  the  name  cannot  be
              resolved  to  a  valid address, Pound will assume that it represents the path for a
              Unix-domain socket. This is a mandatory parameter.

       Port port
              The port number that Pound will connect to. This is a mandatory parameter  for  non
              Unix-domain back-ends.

       HTTPS [ "cert" ]
              The  back-end  is  using  HTTPS. If the optional parameter cert is specified, Pound
              will present this certificate to the back-end.

       Priority val
              The priority of this back-end (between 1 and 9,  5  is  default).  Higher  priority
              back-ends  will  be  used more often than lower priority ones, so you should define
              higher priorities for more capable servers.

       TimeOut val
              Override the global TimeOut value.

       ConnTO val
              Override the global ConnTO value.

       HAport [ address ] port
              A port (and optional address) to be used for server function checks. See below  the
              "High  Availability"  section for a more detailed discussion. By default Pound uses
              the same address as the back-end server, but you may use a separate address if  you
              wish. This directive applies only to non Unix-domain servers.

       Disabled 0|1
              Start Pound with this back-end disabled (1) or enabled (0). If started as disabled,
              the back-end can be later enabled with poundctl (8).

Emergency

       The  emergency  server  will  be  used  once  all  existing  back-ends  are  "dead".   All
       configuration  directives  enclosed  between  Emergency  and  End are specific to a single
       service. The following directives are available:

       Address address
              The address that Pound will connect to. This can be a  numeric  IP  address,  or  a
              symbolic  host  name  that  must  be  resolvable at run-time. If the name cannot be
              resolved to a valid address, Pound will assume that it represents the  path  for  a
              Unix-domain socket. This is a mandatory parameter.

       Port port
              The  port  number that Pound will connect to. This is a mandatory parameter for non
              Unix-domain back-ends.

Session

       Defines how a service deals with possible HTTP  sessions.   All  configuration  directives
       enclosed  between  Session  and  End  are specific to a single service. Once a sessions is
       identified, Pound will attempt to send all requests within that session to the same  back-
       end server.

       The following directives are available:

       Type IP|BASIC|URL|PARM|COOKIE|HEADER
              What  kind  of  sessions  are we looking for: IP (the client address), BASIC (basic
              authentication), URL (a request parameter),  PARM  (a  URI  parameter),  COOKIE  (a
              certain  cookie),  or  HEADER  (a  certain  request  header).   This is a mandatory
              parameter.

       TTL seconds
              How long can a session be idle (in seconds). A  session  that  has  been  idle  for
              longer than the specified number of seconds will be discarded.  This is a mandatory
              parameter.

       ID "name"
              The session identifier. This directive is permitted only for sessions of  type  URL
              (the  name  of  the  request  parameter  we need to track), COOKIE (the name of the
              cookie) and HEADER (the header name).

       See below for some examples.

HIGH-AVAILABILITY

       Pound attempts to keep track of active back-end  servers,  and  will  temporarily  disable
       servers  that do not respond (though not necessarily dead: an overloaded server that Pound
       cannot establish a connection to will be considered dead). However, every  Alive  seconds,
       an  attempt  is made to connect to the dead servers in case they have become active again.
       If this attempt succeeds, connections will be initiated to them again.

       In general it is a good idea to set this time interval as low as is consistent  with  your
       resources  in  order to benefit from resurected servers at the earliest possible time. The
       default value of 30 seconds is probably a good choice.

       The clients that happen upon a dead  backend  server  will  just  receive  a  503  Service
       Unavailable message.

       The HAport parameter specifies an additional port (and optionally an address) that is used
       only for viability checks: if this port is specified in a BackEnd  directive,  Pound  will
       attempt  periodically  (every Alive seconds) to connect to this port. If the port does not
       respond the server is considered dead.  It never makes sense to have the HAport  identical
       to  the  main  back-end  port: this would only generate extra, unncecessary activity (CPU,
       network traffic) for no good reason whatsoever.  The HAport is meant for applications that
       offer  an additional health monitoring port or for installations that wish to take servers
       off-line in a controlled manner.

       By default the address of the HAport health monitor is the same as that  of  the  back-end
       server.  You  may specify a different address though, for example if you have a monitoring
       program running on another host.

HTTPS HEADERS

       If a client browser connects to Pound via HTTPS and if it presents  a  client  certificate
       Pound adds the following headers to the request it issues to the server:

       X-SSL-Subject
              Details about the certificate owner.

       X-SSL-Issuer
              Details about the certificate issuer (Certificate Authority).

       X-SSL-notBefore
              Starting date of certificate validity.

       X-SSL-notAfter
              Ending date of certificate validity.

       X-SSL-serial
              Certificate serial number (decimal).

       X-SSL-cipher
              The cipher currently in use.

       X-SSL-certificate
              The full client certificate (PEM-format multi-line)

       It  is  the application's responsibility to actually use these headers - Pound just passes
       this information without checking it in any  way  (except  for  signature  and  encryption
       correctness).

SECURITY

       In  general, Pound does not read or write to the hard-disk. The exceptions are reading the
       configuration file and (possibly) the server certificate  file(s)  and  error  message(s),
       which  are opened read-only on startup, read, and closed, and the pid file which is opened
       on start-up, written to and immediately closed.  Following this there is  no  disk  access
       whatsoever, so using a RootJail directive is only for extra security bonus points.

       Pound  tries  to sanitise all HTTP/HTTPS requests: the request itself, the headers and the
       contents are checked for conformance to the RFC's and only valid requests  are  passed  to
       the  back-end  servers.  This  is not absolutely fool-proof - as the recent Apache problem
       with chunked transfers demonstrated. However, given the current  standards,  this  is  the
       best that can be done - HTTP is an inherently weak protocol.

ADDITIONAL NOTES

       Pound  uses  the system log for messages (default facility LOG_DAEMON). The format is very
       similar to other web servers, so that if you want to use a log tool:

           fgrep pound /var/log/messages | your_log_tool

       Translating HTTPS to HTTP is an iffy proposition: no client information is passed  to  the
       server itself (certificates, etc) and the backend server may be misled if it uses absolute
       URLs. A patch for Zope is included in the distribution to address this issue -  for  other
       Web servers you are on your own. May the source be with you.

       Pound  deals  with  (and  sanitizes)  HTTP/1.1 requests. Thus even if you have an HTTP/1.0
       server, a single connection to an HTTP/1.1 client is kept, while  the  connection  to  the
       back-end server is re-opened as necessary.

       Pound  attempts  to  resolve the names of the hosts that appear in various requests and/or
       responses.  That means it need a functioning resolver of some kind (be it /etc/hosts,  DNS
       or something else).

EXAMPLES

       To  translate  HTTPS  requests  to  a  local HTTP server (assuming your network address is
       123.123.123.123):

              ListenHTTPS
                  Address 1.2.3.4
                  Port    443
                  Cert    "/etc/pound/server.pem"

                  Service
                      BackEnd
                          Address 127.0.0.1
                          Port    80
                      End
                  End
              End

       To distribute the HTTP/HTTPS requests to three Web servers, where the third one is a newer
       and faster machine:

              ListenHTTP
                  Address 123.123.123.123
                  Port    80
              End
              ListenHTTPS
                  Address 1.2.3.4
                  Port    443
                  Cert    "/etc/pound/server.pem"
              End

              Service
                  BackEnd
                      Address 192.168.0.10
                      Port    80
                  End
                  BackEnd
                      Address 192.168.0.11
                      Port    80
                  End
                  BackEnd
                      Address 192.168.0.12
                      Port    80
                      Priority 3
                  End
              End

       To  separate  between  image  requests  and  other Web content and send all requests for a
       specific URL to a secure server:

              ListenHTTP
                  Address 123.123.123.123
                  Port    80
              End

              # Images server(s)
              Service
                  URL ".*.(jpg|gif)"
                  BackEnd
                      Address 192.168.0.12
                      Port    80
                  End
              End

              # redirect all requests for /forbidden
              Service
                  Url         "/forbidden.*"
                  Redirect    "https://xyzzy.com"
              End

              # Catch-all server(s)
              Service
                  BackEnd
                      Address 192.168.0.10
                      Port    80
                  End
                  BackEnd
                      Address 192.168.0.11
                      Port    80
                  End
                  Session
                      Type    BASIC
                      TTL     300
                  End
              End

       Here is a more complex example: assume your static images (GIF/JPEG) are to be served from
       a  single  back-end  192.168.0.10.  In  addition,  192.168.0.11  is  to do the hosting for
       www.myserver.com with URL-based sessions, and 192.168.0.20 (a 1GHz PIII) and  192.168.0.21
       (800Mhz  Duron)  are  for all other requests (cookie-based sessions).  The logging will be
       done by the back-end servers.  The configuration file may look like this:

              User        "nobody"
              Group       "nogroup"
              RootJail    "/var/pound/jail"
              Alive       60
              LogLevel    0

              # Main listening ports
              ListenHTTP
                  Address 1.2.3.4
                  Port    80
                  Client  10
              End
              ListenHTTPS
                  Address 1.2.3.4
                  Port    443
                  Cert    "/etc/pound/pound.pem"
                  Client  20
              End

              # Image server
              Service
                  URL ".*.(jpg|gif)"
                  BackEnd
                      Address 192.168.0.10
                      Port    80
                  End
              End

              # Virtual host www.myserver.com
              Service
                  URL         ".*sessid=.*"
                  HeadRequire "Host:.*www.myserver.com.*"
                  BackEnd
                      Address 192.168.0.11
                      Port    80
                  End
                  Session
                      Type    URL
                      ID      "sessid"
                      TTL     120
                  End
              End

              # Everybody else
              Service
                  BackEnd
                      Address 192.168.0.20
                      Port    80
                      Priority 5
                  End
                  BackEnd
                      Address 192.168.0.21
                      Port    80
                      Priority 4
                  End
                  Session
                      Type    COOKIE
                      ID      "userid"
                      TTL     180
                  End
              End

FILES

       /var/run/pound.nnn
              this is where Pound will attempt to record its process id.

       /usr/local/etc/pound.cfg
              the default configuration file (the location may be changed when  compiling  -  see
              the F_CONF flag in the Makefile).

       /usr/local/etc/pound/cert.pem
              the   certificate   file(s)  for  HTTPS.  The  location  must  be  defined  in  the
              configuration file - this is only a suggestion. The file must contain a PEM-encoded
              certificate,  optionally  a certificate chain from a known Certificate Authority to
              your server certificate and a PEM-encoded private key (not password protected). See
              OpenSSL(1)  for details. This file should be well protected, lest someone gets your
              server private key.

AUTHOR

       Written by Robert Segall, Apsis GmbH.

REPORTING BUGS

       Report bugs to <roseg@apsis.ch>.

COPYRIGHT

       Copyright © 2002-2010 Apsis GmbH.
       This is free software; see the source for copying conditions.  There is NO  warranty;  not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.