[DOC] add configuration samples

configuration.txt is thorough and accurate but lacked sample configurations
clarifying both the syntax and the relations between global, defaults,
frontend, backend and listen sections. Besides, almost all examples to be found
in haproxy-en.txt or online tutorials make use of the 'listen' syntax while
'frontend/backend' is really the one to know about.
(cherry picked from commit 01ac10ad189b11c563eeb835733fba58e6c5271d)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index d328970ecaa575cb4c819d641e6c1739a77979f7..11c7a1ae2a38040c7d9c91a0b9840bf216156f0d 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -37,6 +37,7 @@ Summary
 2.    Configuring HAProxy
 2.1.      Configuration file format
 2.2.      Time format
+2.3.      Examples
 
 3.    Global parameters
 3.1.      Process management and security
@@ -370,6 +371,52 @@ for every keyword. Supported units are :
   - d  : days.    1d = 24h = 1440m = 86400s = 86400000ms
 
 
+2.3. Examples
+-------------
+
+    # Simple configuration for an HTTP proxy listening on port 80 on all
+    # interfaces and forwarding requests to a single backend "servers" with a
+    # single server "server1" listening on 127.0.0.1:8000
+    global
+        daemon
+        maxconn 256
+
+    defaults
+        mode http
+        timeout connect 5000ms
+        timeout client 50000ms
+        timeout server 50000ms
+
+    frontend http-in
+        bind *:80
+        default_backend servers
+
+    backend servers
+        server server1 127.0.0.1:8000 maxconn 32
+
+
+    # The same configuration defined with a single listen block. Shorter but
+    # less expressive, especially in HTTP mode.
+    global
+        daemon
+        maxconn 256
+
+    defaults
+        mode http
+        timeout connect 5000ms
+        timeout client 50000ms
+        timeout server 50000ms
+
+    listen http-in
+        bind *:80
+        server server1 127.0.0.1:8000 maxconn 32
+
+
+Assuming haproxy is in $PATH, test these configurations in a shell with:
+
+    $ sudo haproxy -f configuration.conf -d
+
+
 3. Global parameters
 --------------------