document how to restrict a firewall to a specific host

xabbuh · weaverryan · commit 14c538217b32 · 2013-12-17T15:31:16.000-06:00
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -132,6 +132,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
@@ -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
@@ -10,6 +10,7 @@ Security
     acl
     acl_advanced
     force_https
+    host_restriction
     form_login
     securing_services
     custom_provider
