diff --git a/components/http_foundation/index.rst b/components/http_foundation/index.rst
index d36849dc5f3..8086085daaa 100644
--- a/components/http_foundation/index.rst
+++ b/components/http_foundation/index.rst
@@ -5,3 +5,4 @@ HTTP Foundation
     :maxdepth: 2
 
     introduction
+    trusting_proxies
diff --git a/components/http_foundation/trusting_proxies.rst b/components/http_foundation/trusting_proxies.rst
new file mode 100644
index 00000000000..efe0c83a446
--- /dev/null
+++ b/components/http_foundation/trusting_proxies.rst
@@ -0,0 +1,49 @@
+.. index::
+   single: Request; Trusted Proxies
+
+Trusting Proxies
+================
+
+If you find yourself behind some sort of proxy - like a load balancer - then
+certain header information may be sent to you using special ``X-Forwarded-*``
+headers. For example, the ``Host`` HTTP header is usually used to return
+the requested host. But when you're behind a proxy, the true host may be
+stored in a ``X-Forwarded-Host`` header.
+
+Since HTTP headers can be spoofed, Symfony2 does *not* trust these proxy
+headers by default. If you are behind a proxy, you should manually whitelist
+your proxy::
+
+    use Symfony\Component\HttpFoundation\Request;
+
+    $request = Request::createFromGlobals();
+    // only trust proxy headers coming from this IP address
+    $request->setTrustedProxies(array(192.0.0.1));
+
+Configuring Header Names
+------------------------
+
+By default, the following proxy headers are trusted:
+
+* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
+* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
+* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
+* ``X-Forwarded-Proto`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getScheme` and :method:`Symfony\\Component\\HttpFoundation\\Request::isSecure`;
+
+If your reverse proxy uses a different header name for any of these, you
+can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
+
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, 'X-Proxy-Proto');
+
+Not trusting certain Headers
+----------------------------
+
+By default, if you whitelist your proxy's IP address, then all four headers
+listed above are trusted. If you need to trust some of these headers but
+not others, you can do that as well::
+
+    // disables trusting the ``X-Forwarded-Proto`` header, the default header is used
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');
diff --git a/components/map.rst.inc b/components/map.rst.inc
index 318fad978f7..8f9e1464da5 100644
--- a/components/map.rst.inc
+++ b/components/map.rst.inc
@@ -49,6 +49,7 @@
 * :doc:`/components/http_foundation/index`
 
   * :doc:`/components/http_foundation/introduction`
+  * :doc:`/components/http_foundation/trusting_proxies`
 
 * :doc:`/components/http_kernel/index`
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
index bcfff139329..39a575e0aef 100644
--- a/reference/configuration/framework.rst
+++ b/reference/configuration/framework.rst
@@ -91,9 +91,42 @@ services related to testing your application (e.g. ``test.client``) are loaded.
 This setting should be present in your ``test`` environment (usually via
 ``app/config/config_test.yml``). For more information, see :doc:`/book/testing`.
 
+trusted_proxies
+~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+Configures the IP addresses that should be trusted as proxies. For more details,
+see :doc:`/components/http_foundation/trusting_proxies`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        framework:
+            trusted_proxies:  [192.0.0.1]
+
+    .. code-block:: xml
+
+        <framework:config trusted-proxies="192.0.0.1">
+            <!-- ... -->
+        </framework>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('framework', array(
+            'trusted_proxies' => array('192.0.0.1'),
+        ));
+
 trust_proxy_headers
 ~~~~~~~~~~~~~~~~~~~
 
+.. caution::
+
+    The ``trust_proxy_headers`` option is deprecated and will be removed in
+    Symfony 2.3. See `trusted_proxies`_ and :doc:`/components/http_foundation/trusting_proxies`
+    for details on how to properly trust proxy data.
+
 **type**: ``Boolean``
 
 Configures if HTTP headers (like ``HTTP_X_FORWARDED_FOR``, ``X_FORWARDED_PROTO``, and