Revise router customization documentation

architecture/core_concepts/routes.adoc

@@ -207,21 +207,23 @@ $ oc set env dc/router HAPROXY_ROUTER_SYSLOG_ADDRESS=127.0.0.1 HAPROXY_ROUTER_LO
 |`*DEFAULT_CERTIFICATE*` |  | The contents of a default certificate to use for routes that don't expose a TLS server cert; in PEM format.
 |`*DEFAULT_CERTIFICATE_DIR*` |  | A path to a directory that contains a file named *_tls.crt_*. If *_tls.crt_* is not a PEM file which also contains a private key, it is first combined with a file named tls.key in the same directory. The PEM-format contents are then used as the default certificate. Only used if `DEFAULT_CERTIFICATE` or `DEFAULT_CERTIFICATE_PATH` are not specified.
 |`*DEFAULT_CERTIFICATE_PATH*` |  | A path to default certificate to use for routes that don't expose a TLS server cert; in PEM format. Only used if `DEFAULT_CERTIFICATE` is not specified.
-|`*EXTENDED_VALIDATION*` | true | If `true`,perform an additional extended validation step on all routes admitted by this router.
+|`*EXTENDED_VALIDATION*` | `true` | If `true`, perform an additional extended validation step on all routes admitted by this router.
 |`*NAMESPACE_LABELS*` |  | A label selector to apply to namespaces to watch, empty means all.
 |`*PROJECT_LABELS*` |  | A label selector to apply to projects to watch, emtpy means all.
 |`*RELOAD_SCRIPT*` |  | The path to the reload script to use to reload the router.
 |`*ROUTER_ALLOWED_DOMAINS*` | | A comma-separated list of domains that the host name in a route can only be part of. Any subdomain in the domain can be used. Option `ROUTER_DENIED_DOMAINS` overrides any values given in this option. If set, everything outside of the allowed domains will be rejected.
-|`*ROUTER_BACKEND_CHECK_INTERVAL*` | 5000ms | Length of time between subsequent "liveness" checks on backends.
+|`*ROUTER_BACKEND_CHECK_INTERVAL*` | 5000ms | Length of time between subsequent "liveness" checks on backends. xref:time-units[(TimeUnits)]
 |`*ROUTER_COMPRESSION_MIME*` | "text/html text/plain text/css" | A space separated list of mime types to compress.
-|`*ROUTER_DEFAULT_CLIENT_TIMEOUT*`| 30s | Length of time within which a client has to acknowledge or send data.
-|`*ROUTER_DEFAULT_CONNECT_TIMEOUT*`| 5s | The maximum connect time.
-|`*ROUTER_DEFAULT_SERVER_TIMEOUT*`| 30s | Length of time within which a server has to acknowledge or send data.
-|`*ROUTER_DEFAULT_TUNNEL_TIMEOUT*` | 1h | Length of time till which TCP or WebSocket connections will remain open.
+|`*ROUTER_DEFAULT_CLIENT_TIMEOUT*`| 30s | Length of time within which a client has to acknowledge or send data. xref:time-units[(TimeUnits)]
+|`*ROUTER_DEFAULT_CONNECT_TIMEOUT*`| 5s | The maximum connect time. xref:time-units[(TimeUnits)]
+|`*ROUTER_DEFAULT_SERVER_TIMEOUT*`| 30s | Length of time within which a server has to acknowledge or send data.  xref:time-units[(TimeUnits)]
+|`*ROUTER_DEFAULT_TUNNEL_TIMEOUT*` | 1h | Length of time till which TCP or WebSocket connections will remain open. If you have websockets/tcp
+connections (and any time HAProxy is reloaded), the old HAProxy processes
+will "linger" around for that period. xref:time-units[(TimeUnits)]
 |`*ROUTER_DENIED_DOMAINS*` | | A comma-separated list of domains that the host name in a route can not be part of. No subdomain in the domain can be used either. Overrides option `ROUTER_ALLOWED_DOMAINS`.
-|`*ROUTER_ENABLE_COMPRESSION*`| false | If `true`, compress responses when possible.
+|`*ROUTER_ENABLE_COMPRESSION*`| | If `true` or `TRUE`, compress responses when possible.
 |`*ROUTER_LOG_LEVEL*` | warning | The log level to send to the syslog server.
-|`*ROUTER_MAX_CONNECTIONS*`| 2000 | Maximum number of concurrent connections.
+|`*ROUTER_MAX_CONNECTIONS*`| 20000 | Maximum number of concurrent connections.
 |`*ROUTER_OVERRIDE_HOSTNAME*`|  | If set `true`, override the spec.host value for a route with the template in `ROUTER_SUBDOMAIN`.
 |`*ROUTER_SERVICE_HTTPS_PORT*` | 443 | Port to listen for HTTPS requests.
 |`*ROUTER_SERVICE_HTTP_PORT*` | 80 | Port to listen for HTTP requests.
@@ -230,9 +232,9 @@ $ oc set env dc/router HAPROXY_ROUTER_SYSLOG_ADDRESS=127.0.0.1 HAPROXY_ROUTER_LO
 |`*ROUTER_SERVICE_NAMESPACE*` |  | The namespace the router identifies itself in the in route status. Required if `ROUTER_SERVICE_NAME` is used.
 |`*ROUTER_SERVICE_NO_SNI_PORT*` | 10443 | Internal port for some front-end to back-end communication (see note below).
 |`*ROUTER_SERVICE_SNI_PORT*` | 10444 | Internal port for some front-end to back-end communication (see note below).
-|`*ROUTER_SLOWLORIS_HTTP_KEEPALIVE*` | 300s | Set the maximum time to wait for a new HTTP request to appear. If this is set too low, it can confuse browsers and applications not expecting a small `keepalive` value.
-|`*ROUTER_SLOWLORIS_TIMEOUT*` | 10s | Length of time the transmission of an HTTP request can take.
-|`*ROUTER_SUBDOMAIN*`|  | The template that should be used to generate the host name for a route without spec.host (e.g. `${name}-${namespace}.myapps.mycompany.com`).
+| `*ROUTER_SLOWLORIS_HTTP_KEEPALIVE*`| 300s | Set the maximum time to wait for a new HTTP request to appear. If this is set too low, it can confuse browsers and applications not expecting a small `keepalive` value. xref:time-units[(TimeUnits)]
+|`*ROUTER_SLOWLORIS_TIMEOUT*` | 10s | Length of time the transmission of an HTTP request can take. xref:time-units[(TimeUnits)]
+|`*ROUTER_SUBDOMAIN*`|  | The template that should be used to generate the host name for a route without spec.host (e.g. ${name}-${namespace}.myapps.mycompany.com).
 |`*ROUTER_SYSLOG_ADDRESS*` |  | Address to send log messages. Disabled if empty.
 |`*ROUTER_TCP_BALANCE_SCHEME*` | source | Load-balancing strategy for multiple endpoints for pass-through routes. Available options are `source`, `roundrobin`, or `leastconn`.
 |`*ROUTER_LOAD_BALANCE_ALGORITHM*` | leastconn | Load-balancing strategy routes with multiple endpoints. Available options are `source`, `roundrobin`, and `leastconn`.
@@ -241,11 +243,19 @@ $ oc set env dc/router HAPROXY_ROUTER_SYSLOG_ADDRESS=127.0.0.1 HAPROXY_ROUTER_LO
 |`*STATS_PASSWORD*` |  | The password needed to access router stats (if the router implementation supports it).
 |`*STATS_PORT*` |  | Port to expose statistics on (if the router implementation supports it).  If not set, stats are not exposed.
 |`*STATS_USERNAME*` |  | The user name needed to access router stats (if the router implementation supports it).
-|`*TEMPLATE_FILE*` | `/var/lib/haproxy/conf/custom/haproxy-config-custom.template` | The path to the HAproxy template file (in the image).
-|`*RELOAD_INTERVAL*` | 12s | The minimum frequency the router is allowed to reload to accept new changes.
-|`*ROUTER_DISABLE_NAMESPACE_OWNERSHIP_CHECK*` |  | Set to "true" to relax the namespace ownership policy.
+|`*TEMPLATE_FILE*` | `/var/lib/haproxy/conf/custom/` `haproxy-config-custom.template` | The path to the HAProxy template file (in the container image).
+|`*RELOAD_INTERVAL*` | 12s | The minimum frequency the router is allowed to reload to accept new changes. xref:time-units[(TimeUnits)]
+|`*ROUTER_USE_PROXY_PROTOCOL*`|  | When set to `true` or `TRUE`, HAProxy expects incoming connections to use the `PROXY` protocol on port 80 or port 443. The source IP address can pass through a load balancer if the load balancer supports the protocol, for example Amazon ELB.
+|`*ROUTER_ALLOW_WILDCARD_ROUTES*`|  |  When set to `true` or `TRUE`, any routes with a wildcard policy of `Subdomain` that pass the router admission checks will be serviced by the HAProxy router.
+|`*ROUTER_DISABLE_NAMESPACE_OWNERSHIP_CHECK*` |  | Set to `true` to relax the namespace ownership policy.
 |===
 
+[[time-units]]
+*TimeUnits* are a number followed by the unit: us(microseconds), ms(milliseconds, default), s(seconds), m(minutes), h(hours), d(days).
+
+
+
+
 [NOTE]
 ====
 If you want to run multiple routers on the same machine, you must
@@ -1002,16 +1012,21 @@ For all the items outlined in this section, you can set annotations on the
 |===
 |Variable | Description | Environment Variable Used as Default
 |`*haproxy.router.openshift.io/balance*`| Sets the load-balancing algorithm. Available options are `source`, `roundrobin`, and `leastconn`. | `ROUTER_TCP_BALANCE_SCHEME` for passthrough routes. Otherwise, use `ROUTER_LOAD_BALANCE_ALGORITHM`.
-|`*haproxy.router.openshift.io/disable_cookies*`| Disables the use of cookies to track related connections. If set to `true`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request. |
-|`*haproxy.router.openshift.io/rate-limit-connections*`| Setting to `true` enables rate limiting functionality. |
+|`*haproxy.router.openshift.io/disable_cookies*`| Disables the use of cookies to track related connections. If set to `true` or `TRUE`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request. |
+|`*haproxy.router.openshift.io/rate-limit-connections*`| Setting `true` or `TRUE` to enables rate limiting functionality. |
 |`*haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp*`| Limits the number of concurrent TCP connections shared by an IP address. |
 |`*haproxy.router.openshift.io/rate-limit-connections.rate-http*`| Limits the rate at which an IP address can make HTTP requests. |
 |`*haproxy.router.openshift.io/rate-limit-connections.rate-tcp*`| Limits the rate at which an IP address can make TCP connections. |
-|`*haproxy.router.openshift.io/timeout*` | Sets a server-side timeout. | `ROUTER_DEFAULT_SERVER_TIMEOUT`
-|`*router.openshift.io/haproxy.health.check.interval*`| Sets the interval for the back-end health checks. | `ROUTER_BACKEND_CHECK_INTERVAL`
+|`*haproxy.router.openshift.io/timeout*` | Sets a server-side timeout for the route. xref:time-units[(TimeUnits)] | `ROUTER_DEFAULT_SERVER_TIMEOUT`
+|`*router.openshift.io/haproxy.health.check.interval*`| Sets the interval for the back-end health checks. xref:time-units[(TimeUnits)] | `ROUTER_BACKEND_CHECK_INTERVAL`
 |===
 
 
+[[time-units]]
+*TimeUnits* are a number followed by the unit: us, ms, s, m, h, d. The regular expression is:
+[1-9][0-9]*(us\|ms\|s\|m\|h\|d)
+
+
 .A Route Setting Custom Timeout
 ====
 [source,yaml]
@@ -1110,7 +1125,7 @@ $ oc set env dc/myrouter ROUTER_DENIED_DOMAINS="open.header.test, openshift.org,
 This means that `myrouter` will admit the following based on the route's name:
 
 ----
-$ oc expose service/<name> --hostname="foo.header.test" 
+$ oc expose service/<name> --hostname="foo.header.test"
 $ oc expose service/<name> --hostname="www.allow.it"
 $ oc expose service/<name> --hostname="www.openshift.test"
 ----
@@ -1137,8 +1152,8 @@ This means that the `myrouter` router will admit:
 
 ----
 $ oc expose service/<name> --hostname="stickshift.org"
-$ oc expose service/<name> --hostname="www.stickshift.org" 
-$ oc expose service/<name> --hostname="kates.net" 
+$ oc expose service/<name> --hostname="www.stickshift.org"
+$ oc expose service/<name> --hostname="kates.net"
 $ oc expose service/<name> --hostname="api.kates.net"
 $ oc expose service/<name> --hostname="erno.r.kube.kates.net"
 ----