From 09e06f42c1597c1553b085945477d88f8c14fbf3 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sun, 15 Sep 2013 15:17:31 +0200
Subject: [PATCH] document how to restrict a firewall to a specific host

---
 cookbook/map.rst.inc                   |  1 +
 cookbook/security/host_restriction.rst | 62 ++++++++++++++++++++++++++
 cookbook/security/index.rst            |  1 +
 3 files changed, 64 insertions(+)
 create mode 100644 cookbook/security/host_restriction.rst

diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
index d98207e594d..c361ec30426 100644
--- a/cookbook/map.rst.inc
+++ b/cookbook/map.rst.inc
@@ -126,6 +126,7 @@
   * :doc:`/cookbook/security/acl`
   * :doc:`/cookbook/security/acl_advanced`
   * :doc:`/cookbook/security/force_https`
+  * :doc:`/cookbook/security/host_restriction`
   * :doc:`/cookbook/security/form_login`
   * :doc:`/cookbook/security/securing_services`
   * :doc:`/cookbook/security/custom_provider`
diff --git a/cookbook/security/host_restriction.rst b/cookbook/security/host_restriction.rst
new file mode 100644
index 00000000000..fcb2960651b
--- /dev/null
+++ b/cookbook/security/host_restriction.rst
@@ -0,0 +1,62 @@
+.. index::
+   single: Security; Restrict Security Firewalls to a Host
+
+How to restrict Firewalls to a Specific Host
+============================================
+
+.. versionadded:: 2.4
+    Support for restricting security firewalls to a specific host was added in
+    Symfony 2.4.
+
+When using the Security component, you can create firewalls that match certain
+url patterns and thereby restrict access to all urls matching these patterns.
+Additionally, you can restrict a firewall to a host using the ``host`` key:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+
+        # ...
+
+        security:
+            firewalls:
+                secured_area:
+                    pattern:    ^/
+                    host:       admin\.example\.com
+                    http_basic: true
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <firewall name="secured_area" pattern="^/" host="admin.example.com">
+                    <http-basic />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+
+        // ...
+
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    'pattern'    => '^/',
+                    'host'       => 'admin.example.com',
+                    'http_basic' => true,
+                ),
+            ),
+        ));
diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst
index a8edbdc4317..69a90e7636b 100644
--- a/cookbook/security/index.rst
+++ b/cookbook/security/index.rst
@@ -10,6 +10,7 @@ Security
     acl
     acl_advanced
     force_https
+    host_restriction
     form_login
     securing_services
     custom_provider