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(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: 18.104.22.168 Port: 80 Services: - Backends: - *be HTTPSListeners: The same thing, but with HTTPS: Backends: - &be Address: 10.1.1.100 Port: 80 HTTPListeners: HTTPSListeners: - Address: 22.214.171.124 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: 126.96.36.199 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: 188.8.131.52 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 <firstname.lastname@example.org>. 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)