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:
Global:
- Err500: /usr/local/etc/pound_error_500
- Group: root
- User: root
Backends:
- &be
Address: 127.0.0.1
Port: 9000
HTTPListeners:
- Address: 0.0.0.0
Port: 80
Services:
- Backends:
- *be
HTTPSListeners:
- Address: 0.0.0.0
Certificates:
- /etc/pound/certbot/combined-for-pound.pem
Port: 443
Services:
- Backends:
- *be
This is the output from running Pound from the command line:
$ sudo pound -d 5
debug option 5 ./src/config.c:642
start get_others ./src/config.c:574
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_https ./src/config.c:499
address 0.0.0.0 ./src/config.c:520
start get_certificates ./src/config.c:461
start get_one(/etc/pound/certbot/combined-for-pound.pem) ./src/config.c:376
get_one add pattern scalacourses\.com ./src/config.c:406
get_one add pattern home\.scalacourses\.com ./src/config.c:432
get_one add pattern scalacourses\.com ./src/config.c:432
get_one add pattern www\.scalacourses\.com ./src/config.c:432
get_one: added 4 patterns ./src/config.c:446
port 443 ./src/config.c:523
start get_services ./src/config.c:209
push ./src/config.c:258
push ./src/config.c:562
Prepare backends ./src/pound.c:153
Starting resurrector thread ./src/util.c:80
Prepare listeners ./src/pound.c:185
Prepare services for listener 0 ./src/pound.c:188
7F1B0827A640 start service ./src/http.c:45
7F1B0827A640 Null session: ./src/http.c:52
7F1B07A79640 thr_http start ./src/http.c:535
7F1B07A79640 start loop ./src/http.c:539
7F1B07278640 thr_http start ./src/http.c:535
7F1B07278640 start loop ./src/http.c:539
7F1B06A77640 thr_http start ./src/http.c:535
7F1B06A77640 start loop ./src/http.c:539
7F1B06276640 thr_http start ./src/http.c:535
7F1B06276640 start loop ./src/http.c:539
7F1B05A75640 thr_http start ./src/http.c:535
7F1B05A75640 start loop ./src/http.c:539
7F1B05274640 thr_http start ./src/http.c:535
7F1B05274640 start loop ./src/http.c:539
7F1B04A73640 thr_http start ./src/http.c:535
7F1B04A73640 start loop ./src/http.c:539
7F1B04272640 thr_http start ./src/http.c:535
7F1B04272640 start loop ./src/http.c:539
7F1B04272640 peer address 192.168.1.1 ./src/http.c:549
7F1B04272640 start sni ./src/util.c:157
7F1B04272640 sni for scalacourses.com ./src/util.c:165
7F1B04272640: found match at 0 ./src/util.c:169
Segmentation fault
The segmentation fault happens after I attempt to connect to the website from another machine by using https://scalacourses.com/
$ lynx https://scalacourses.com/
Looking up scalacourses.com
Making HTTPS connection to scalacourses.com
Alert!: Unable to make secure connection to remote host.
lynx: Can't access startfile https://scalacourses.com/
After the core dump, the socket remains in use for a few minutes before Pound can be restarted:
Listener 0.0.0.0:https: can't bind socket
When I try to access without SSL (http://scalacourses.com/ and http://www.scalacourses.com/) Pound does not appear to respond, and I get:
$ lynx http://scalacourses.com/
Looking up scalacourses.com
Making HTTP connection to scalacourses.com
Sending HTTP request.
HTTP request sent; waiting for response.
HTTP/1.1 302 Found
Data transfer complete
HTTP/1.1 302 Found
Using http://www.scalacourses.com/
Looking up www.scalacourses.com
Making HTTP connection to www.scalacourses.com
Alert!: Unable to connect to remote host.
lynx: Can't access startfile http://scalacourses.com/
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 <[email protected]>.
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)
Pound is effectively a dead project. Anything that Pound can do as a reverse proxy, Apache http and nginx can do, and do better.
I chose nginx. You can read about the gory details here: https://www.mslinn.com/blog/2022/07/08/reverse-proxy.html