[#2953][#2986] Tweaks to firewall hostname

weaverryan · weaverryan · commit 0a9241d1756a · 2013-12-17T15:31:29.000-06:00
Biggest change is to clarify that matching a firewall has no guarantee (is unrelated)
to whether or not access is restricted. Also, fixed up some of the regex.
diff --git a/cookbook/security/host_restriction.rst b/cookbook/security/host_restriction.rst
@@ -1,16 +1,17 @@
 .. index::
    single: Security; Restrict Security Firewalls to a Host
 
-How to restrict Firewalls to a Specific 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:
+URL patterns and therefore are activated for all pages whose URL matches
+that pattern. Additionally, you can restrict the initialization of a firewall
+to a host using the ``host`` key:
 
 .. configuration-block::
 
@@ -24,7 +25,7 @@ Additionally, you can restrict a firewall to a host using the ``host`` key:
             firewalls:
                 secured_area:
                     pattern:    ^/
-                    host:       admin\.example\.com
+                    host:       ^admin\.example\.com$
                     http_basic: true
 
     .. code-block:: xml
@@ -39,7 +40,7 @@ Additionally, you can restrict a firewall to a host using the ``host`` key:
 
             <config>
                 <!-- ... -->
-                <firewall name="secured_area" pattern="^/" host="admin.example.com">
+                <firewall name="secured_area" pattern="^/" host="^admin\.example\.com$">
                     <http-basic />
                 </firewall>
             </config>
@@ -55,8 +56,15 @@ Additionally, you can restrict a firewall to a host using the ``host`` key:
             'firewalls' => array(
                 'secured_area' => array(
                     'pattern'    => '^/',
-                    'host'       => 'admin.example.com',
+                    'host'       => '^admin\.example\.com$',
                     'http_basic' => true,
                 ),
             ),
         ));
+
+The ``host`` (like the ``path``) is a regular expression. In this example,
+the firewall will only be activated if the host is equal exactly (due to
+the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
+If the hostname does not match this pattern, the firewall will not be activated
+and subsequent firewalls will have the opportunity to be matched for this
+request.
