Convert Pound 2.8 Configuration file to 3.x YAML

I have this v2.8-2 configuration file that I want to convert to the new YAML format. Documentation is hard to find.

User    "root"
Group   "root"
LogLevel 5
Alive    10
Control "/var/run/poundctl.socket"

# Redirect all http requests on port 80 to https on port 443
ListenHTTP
  Address 0.0.0.0
  Port 80
  Err500 "/usr/local/etc/pound_error_500"
  Err503 "/usr/local/etc/pound_error_500"
  Service
    Redirect 301 "https://localhost"
  End
End

# Redirect all requests on port 443 to the webapp on port 9443
ListenHTTPS
  Address 0.0.0.0
  Port 443
  Err500 "/usr/local/etc/pound_error_500"
  Err503 "/usr/local/etc/pound_error_500"
  Cert "/etc/pound/certbot/combined-for-pound.pem"
  Disable SSLv3
  Ciphers "EECDH+ECDSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:ECDH+AESGCM:ECDH+AES256:ECDH+AES128:ECDH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!eNULL:!LOW:!aNULL:!MD5:!DSS"
SSLAllowClientRenegotiation     0
  SSLHonorCipherOrder 1
  HeadRemove "X-Forwarded-Proto"
  HeadRemove "x-forwarded-proto"
  AddHeader "x-forwarded-proto: https"
  Service
    BackEnd
      Address 127.0.0.1
      Port 9000
    End
  End
End

This is my attempt at translating the above to the new format:

Backends:
  - &be
    Address: 127.0.0.1
    Port: 9000

Global:
  # Check backend every X secs:
  # Not used for Pound 3.x?
  # Alive: 10

  # poundctl control socket not used for v3?
  # Control: /var/run/poundctl.socket

  # Err404: /usr/local/etc/pound_error_404
  # Err405: /usr/local/etc/pound_error_405
  Err500: /usr/local/etc/pound_error_500
  # Not used for Pound 3.x?
  # Err503: /usr/local/etc/pound_error_500

  Group: root
  User:  root

# This section must exist, but may be empty.
HTTPListeners:
  - Address: 0.0.0.0
  - Port: 80
  - Services:
    - Backends:
      - *be

# This section must exist, but may be empty.
HTTPSListeners:
  - Address: 0.0.0.0
  - Certificates:
    - /etc/pound/certbot/combined-for-pound.pem
    # Ciphers:
    #  - EECDH+ECDSA+AESGCM
    #  - EECDH+ECDSA+SHA384
    #  - EECDH+ECDSA+SHA256
    #  - ECDH+AESGCM
    #  - ECDH+AES256
    #  - ECDH+AES128
    #  - ECDH+3DES
    #  - RSA+AESGCM
    #  - RSA+AES
    #  - RSA+3DES
    #  - !eNULL
    #  - !LOW
    #  - !aNULL
    #  - !MD5
    #  - !DSS
  - Port: 443
  - Services:
    - Backends:
      - *be

When I attempt to run Pound as a daemon, I get: Segmentation fault (core dumped).

This is the output from running Pound from the command line:

$ pound -d 5
debug option 5 ./src/config.c:642
start get_others ./src/config.c:574
start get_global ./src/config.c:74
group 0 ./src/config.c:85
user 0 ./src/config.c:80
start get_backends ./src/config.c:123
addr 127.0.0.1 ./src/config.c:139
port 9000 ./src/config.c:142
push ./src/config.c:168
start get_http ./src/config.c:277
addr 0.0.0.0 ./src/config.c:291
Segmentation fault (core dumped)

Pound also emitted an HTML-formatted directory listing.

Here is the help message for pound v3:

POUND(8)                    System Manager's Manual                   POUND(8)

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

SYNOPSIS
       pound  [-v] [-c] [-d level] [-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. 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 func‐
       tion: 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.
              When a request is received Pound attempts to match them to  each
              service in turn. The services may define their own conditions as
              to which requests they can answer: typically this involves  cer‐
              tain  URLs  (images only, or a certain path) or specific headers
              (such as the Host header).

       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.

              Multiple  back-ends  may be used 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 Unavail‐
              able", 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     Print version: Pound will exit immediately  after  printing  the
              current version.

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

       -d level
              Debug  mode:  if  level is greater than 0 error messages will be
              sent to stdout and Pound will stay in the  foreground.  Level  0
              (default) are the regular log messages, level 1 and up will pro‐
              duce more detailed information.

       -f config_file
              Location of the configuration file (see below  for  a  full  de‐
              scription of the format).  Default: /etc/pound/pound.yaml

       -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

       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 we
       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
       The  configuration  file  is  in  standard  YAML syntax. There are four
       blocks of directives: Global directives (they affect the  settings  for
       the  entire program instance), Backends directives, defining the avail‐
       able backends, HTTPlisteners directives  (they  define  which  requests
       Pound will listen for), and HTTPSlisteners directives (same as HTTPlis‐
       tener but via TLS).

   Global Directives
       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 SSL may require 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.

       Err404: path_to_file
              Specify a path to an HTML file to be returned in case of  a  404
              error.

       Err405: path_to_file
              Specify  a  path to an HTML file to be returned in case of a 405
              error.

       Err500: path_to_file
              Specify a path to an HTML file to be returned in case of  a  500
              error.

   Backends
       A  back-end  is a definition of a single back-end server Pound will use
       to reply to incoming requests. Each backend must be marked with an  an‐
       chor. 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. This is a mandatory parameter.

       Port: port
              The  port number that Pound will connect to. This is a mandatory
              parameter.

       Timeout: number
              How long to wait for a backend (server) to complete  and  opera‐
              tion. Default: 15 seconds.

       Threads: number
              How  many threads will be used to service requests to this back‐
              end. See also below for remarks on performance tuning.  Default:
              8 threads.

       HeadAdd: header
              A  header  to  add to each reply received from this backend. The
              header is a string.

   HTTPListeners
       An HTTP listener defines an address and port that Pound will listen  on
       for HTTP requests. 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.

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

       Client: value
              Define how long Pound will wait for client activity. Default:  5
              seconds.

       Threads: value
              Define  how  many  threads  Pound will use to service client re‐
              quests. Default: 8 threads.

       Services:
              This defines a service. This service will be used only  by  this
              listener.

   Services
       The following directives are allowed in a service definition:

       URL: pattern
              The  service  will  only  be used if the request URL matches the
              given pattern.

       HeadRequire: pattern
              Use the service only if any of the request headers  matches  the
              given pattern.

       HeadDeny: pattern
              Use  the service only if none of the request headers matches the
              given pattern.

       Session: number
              How long to keep the client sessions (in seconds). Sessions  are
              a  long  term association between a client IP address and a spe‐
              cific backend in this service. A value of  0  seconds  means  no
              sessions are kept. Default: 0.

       BackEnds:
              A list of references to previously defined backends.

   HTTPSListeners
       All  HTTPListeners  directives  are also available in the HTTPSListener
       blocks.
        The following additional directives are available:

       Certificates:
              A file name or a list of file names. Each file  must  contain  a
              certificate,  optionally additional chained certificates up to a
              known certificate authority, and the private  key  corresponding
              to  the  certificate.  Note: the private key should probably not
              be password-protected, as Pound normally starts as a daemon  and
              cannot ask for the password at start-up time.

       Ciphers:
              A list of acceptable cipher names for this listener. The negoti‐
              ation with the client will result in one of these ciphers  being
              used, or the hand-shake will fail.

ADDITIONAL REMARKS
   High-availability
       Pound  attempts to keep track of active back-end servers, and will tem‐
       porarily 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 60 seconds  (compile-time  op‐
       tion),  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.

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

Security
       In general, Pound does not read or write to the hard-disk.  The  excep‐
       tions are reading the configuration file and (possibly) the server cer‐
       tificate file(s) and error message(s), which are  opened  read-only  on
       startup,  read,  and  closed;  secondly 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 -
       compile-time option).  The format is very similar to other web servers,
       so if you want to use a log tool:
                  fgrep pound /var/log/messages | cut -d ':' -f 4- | your_log_tool
       (assuming messages is you log file; it may be syslog or something else,
       depending on your configuration).

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

       Unless you start Pound as root it won't be able to listen on privileged
       ports. That applies even if you do start it as root but set the User to
       something else.

       There is no point in setting User to root: either you start as root, so
       you already are, or you are not allowed to setuid(0).

   Performance Tuning Considerations
       The  two  important factors in tuning the performance are the number of
       threads for the backends end the number of threads for the listeners.

       The number of backend threads defines how many requests may  be  issued
       in  parallel to a specific backend server, but also backend priorities.
       Increasing it may overload the web server, but setting it too low  will
       cause  longer  wating ques for servicing requests. Please note that you
       may define several backends for the same server in order to use them in
       separate services.

       The  number of listener threads defines how many client requests can be
       serviced in parallel. If this number is too low for your  load  clients
       may  be faced with long waiting times even when the backends are almost
       idle.

EXAMPLES
       The simplest configuration, with Pound used strictly  to  sanitise  re‐
       quests:
              Backends:
                  - &be
                      Address: 10.1.1.100
                      Port: 80

              HTTPListeners:
                  -   Address: 123.1.2.3
                      Port: 80
                      Services:
                          -   Backends:
                                  - *be

              HTTPSListeners:

       The same thing, but with HTTPS:
              Backends:
                  - &be
                      Address: 10.1.1.100
                      Port: 80

              HTTPListeners:

              HTTPSListeners:
                  -   Address: 123.1.2.3
                      Port: 443
                      Services:
                          -   Backends:
                                  - *be
                      Certificates: "cert.pem"
                      Client: 60
                      Ciphers:
                          - TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384
                          - TLS-DHE-RSA-WITH-3DES-EDE-CBC-SHA
                          - TLS-DHE-RSA-WITH-AES-128-CBC-SHA
                          - TLS-RSA-WITH-CAMELLIA-128-CBC-SHA
                          - TLS-RSA-WITH-AES-128-CCM
                          - TLS-RSA-WITH-AES-256-GCM-SHA384
                          - TLS-RSA-WITH-RC4-128-MD5
                          - TLS-RSA-WITH-3DES-EDE-CBC-SHA

       To  distribute  the HTTP/HTTPS requests to three Web servers, where the
       third one is a newer and faster machine:
              Backends:
                  - &be0
                      Address: 10.1.1.100
                      Port: 80
                      Threads: 8
                  - &be1
                      Address: 10.1.1.101
                      Port: 80
                      Threads: 8
                  - &be2
                      Address: 10.1.1.102
                      Port: 80
                      Threads: 12

              HTTPListeners:

              HTTPSListeners:
                  -   Address: 123.1.2.3
                      Port: 80
                      Threads: 32
                      Services:
                          -   Backends:
                                  - *be0
                                  - *be1
                                  - *be2
                      Certificates:
                          - "cert1.pem"
                          - "cert2.pem"

       To separate between image requests and other Web content:
              Backends:
                  - &text
                      Address: 10.1.1.100
                      Port: 80
                      Threads: 16
                  - &images
                      Address: 10.1.1.101
                      Port: 80
                      Threads: 16

              HTTPListeners:
                  -   Address: 123.1.2.3
                      Port: 80
                      Threads: 32
                      Services:
                          -   URL: ".*.(gif|jpg|png)"
                              Backends:
                                  - *images
                          -   Session: 300
                              Backends:
                                  - *text

              HTTPSListeners:

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

       /etc/pound/pound.yaml
              the default configuration file (compile-time option).

AUTHOR
       Written by Robert Segall, Apsis GmbH.

REPORTING BUGS
       Report bugs to <roseg@apsis.ch>.

COPYRIGHT
       Copyright © 2002-2020 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.

pound                              Jan 2010                           POUND(8)

Leave a Comment