Document the 'trusted_proxy' bit.feature.x_wsgi_url_scheme-header

4 files changed, 20 insertions, 7 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 1722bf9..7fa486b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,9 +1,9 @@
 Unreleased
 ----------
 
-- Allow override of ``wsgi.url_scheme`` via a request header,
+- Allow trusted proxies to override ``wsgi.url_scheme`` via a request header,
   ``X_FORWARDED_PROTO``.  Allows proxies which serve mixed HTTP / HTTPS
-  requests to control signal which are served as HTTPS.See
+  requests to control signal which are served as HTTPS.  See
   https://github.com/Pylons/waitress/pull/42.
 
 0.8.8 (2013-11-30)
diff --git a/docs/arguments.rst b/docs/arguments.rst
index afaf331..f96a3ff 100644
--- a/docs/arguments.rst
+++ b/docs/arguments.rst
@@ -28,9 +28,14 @@ threads
     number of threads used to process application logic (integer), default
     ``4``
 
+trusted_proxy
+    IP addreess of a client allowed to override ``url_scheme`` via the
+    ``X_FORWARDED_PROTO`` header.
+
 url_scheme
     default ``wsgi.url_scheme`` value (string), default ``http``;  can be
-    overridden per-request by the value of the ``X_FORWARDED_PROTO`` header.
+    overridden per-request by the value of the ``X_FORWARDED_PROTO`` header,
+    but only if the client address matches ``trusted_proxy``.
 
 ident
     server identity (string) used in "Server:" header in responses, default
diff --git a/docs/differences.rst b/docs/differences.rst
index e3d9435..f4af227 100644
--- a/docs/differences.rst
+++ b/docs/differences.rst
@@ -13,8 +13,8 @@ Differences from ``zope.server``
 
 - Calls "close()" on the app_iter object returned by the WSGI application.
 
-- Allows per-request override of ``wsgi.url_scheme`` by the value of the
-  ``X_FORWARDED_PROTO`` header
+- Allows trusted proxies to override ``wsgi.url_scheme`` for particular
+  requests by supplying the ``X_FORWARDED_PROTO`` header.
 
 - Supports an explicit ``wsgi.url_scheme`` parameter for ease of deployment
   behind SSL proxies.
diff --git a/docs/index.rst b/docs/index.rst
index 1faa3f4..cf0eef8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -126,7 +126,9 @@ application.  You can do this in one of three ways:
 
 2.  You can configure the proxy reverse server to pass a header,
     ``X_FORWARDED_PROTO``, whose value will be set for that request as
-    the ``wsgi.url_scheme`` environment value.
+    the ``wsgi.url_scheme`` environment value.  Note that you must also
+    conigure ``waitress.serve`` by passing the IP address of that proxy
+    as its ``trusted_proxy``.
 
 3.  You can use Paste's ``PrefixMiddleware`` in conjunction with
     configuration settings on the reverse proxy server.
@@ -147,7 +149,7 @@ Passing the ``X_FORWARDED_PROTO`` header to set ``wsgi.url_scheme``
 
 If your proxy accepts both HTTP and HTTPS URLs, and you want your application
 to generate the appropriate url based on the incoming scheme, also set up
-your proxy to send a ``X-WSGI-Scheme`` with the original URL scheme along
+your proxy to send a ``X-Forwarded-Proto`` with the original URL scheme along
 with each proxied request.  For example, when using Nginx::
 
     proxy_set_header        X-Forwarded-Proto $scheme;
@@ -156,6 +158,12 @@ or via Apache::
 
    RequestHeader set X-Forwarded-Proto https
 
+.. note::
+
+   You must also configure the Waitress server's ``trusted_proxy`` to
+   contain the IP address of the proxy in order for this header to override
+   the default URL scheme.
+
 Using ``url_prefix`` to influence ``SCRIPT_NAME`` and ``PATH_INFO``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~