Update documentation to cover both new and classic config formats

site/access-control.xml

@@ -80,7 +80,7 @@ limitations under the License.
           By default, the <code>guest</code> user is prohibited from
           connecting to the broker remotely; it can only connect over
           a loopback interface (i.e. <code>localhost</code>). This
-          applies both to AMQP and to any other protocols enabled via
+          applies both to AMQP 0-9-1 and to any other protocols enabled via
           plugins. Any other users you create will not (by default) be
           restricted in this way.
         </p>
@@ -92,10 +92,16 @@ limitations under the License.
         <p>
           If you wish to allow the <code>guest</code> user to connect
           from a remote host, you should set the
-          <code>loopback_users</code> configuration item to
-          <code>[]</code>. A complete <code>rabbitmq.config</code>
+          <code>loopback_users</code> configuration to
+          <code>none</code>. A complete <a href="/configure.html">RabbitMQ config file</a>
           which does this would look like:
         </p>
+        <pre class="sourcecode">
+loopback_users = none
+</pre>
+
+        Or, in the <a href="/configure.html#erlang-term-config-file">classic config file format</a> (<code>rabbitmq.config</code>):
+
         <pre class="sourcecode">
 [{rabbit, [{loopback_users, []}]}].</pre>
       </doc:section>
@@ -254,14 +260,14 @@ limitations under the License.
           IP range one</a>, only provide an authorisation backend. Authentication
           is supposed to be handled by the internal database, LDAP, etc.
         </p>
-        
+
         <doc:subsection name="combined-backends">
           <doc:heading>Combining Backends</doc:heading>
 
           <p>
             It is possible to use multiple backends for
             <code>authn</code> or <code>authz</code> using the
-            <code>rabbit.auth_backends</code> configuration key. When
+            <code>auth_backends</code> configuration key. When
             several authentication backends are used then the first
             positive result returned by a backend in the chain is
             considered to be final. This should not be confused with
@@ -273,19 +279,53 @@ limitations under the License.
             The following example configures RabbitMQ to use the internal backend
             only (and is the default):
           </p>
-
+
+<pre class="example">
+# rabbitmq.conf
+#
+# 1 here is a backend name. It can be anything.
+# Since we only really care about backend
+# ordering, we use numbers throughout this guide.
+#
+# "internal" is an alias for rabbit_auth_backend_internal
+auth_backends.1 = internal
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
 <pre class="example">
 [{rabbit, [
             {auth_backends, [rabbit_auth_backend_internal]}
           ]
 }].
 </pre>
 
+          <p>
+            The example above uses an alias, <code>internal</code> for <code>rabbit_auth_backend_internal</code>.
+            The following aliases are available:
+
+            <ul>
+              <li><code>internal</code> for <code>rabbit_auth_backend_internal</code></li>
+              <li><code>ldap</code> for <code>rabbit_auth_backend_ldap</code> (from the <a href="/ldap.html">LDAP plugin</a>)</li>
+              <li><code>http</code> for <code>rabbit_auth_backend_http</code> (from the <a href="https://github.com/rabbitmq/rabbitmq-auth-backend-http">HTTP auth backend plugin</a>)</li>
+              <li><code>amqp</code> for <code>rabbit_auth_backend_amqp</code> (from the <a href="https://github.com/rabbitmq/rabbitmq-auth-backend-amqp">AMQP 0-9-1 auth backend plugin</a>)</li>
+              <li><code>dummy</code> for <code>rabbit_auth_backend_dummy</code></li>
+            </ul>
+
+            When using third party plugins, providing a full module name is necessary.
+          </p>
+
           <p>
             The following example configures RabbitMQ to use the <a href="/ldap.html">LDAP backend</a>
             for both authentication and authorisation. Internal database will not be consulted:
           </p>
-
+
+<pre class="example">
+auth_backends.1 = ldap
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
 <pre class="example">
 [{rabbit, [
             {auth_backends, [rabbit_auth_backend_ldap]}
@@ -297,18 +337,42 @@ limitations under the License.
         This will check LDAP first, and then fall back to the internal
         database if the user cannot be authenticated through LDAP:
       </p>
+
+<pre class="example">
+auth_backends.1 = ldap
+auth_backends.2 = internal
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
       <pre class="example">
 [{rabbit, [
             {auth_backends, [rabbit_auth_backend_ldap, rabbit_auth_backend_internal]}
           ]
 }].
       </pre>
-      
+
       <p>
         Same as above but will fall back to the <a
         href="https://github.com/rabbitmq/rabbitmq-auth-backend-http">HTTP backend</a>
         instead:
       </p>
+
+<pre class="example">
+# rabbitmq.conf
+#
+auth_backends.1 = ldap
+# uses module name instead of a short alias, "http"
+auth_backends.2 = rabbit_auth_backend_http
+
+# See HTTP backend docs for details
+http.user_path = http://my-authenticator-app/auth/user
+http.vhost_path = http://my-authenticator-app/auth/vhost
+http.resource_path = http://my-authenticator-app/auth/resource
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
       <pre class="example">
 [{rabbit, [
             {auth_backends, [rabbit_auth_backend_ldap, rabbit_auth_backend_http]}
@@ -319,16 +383,25 @@ limitations under the License.
    [{user_path,     "http://my-authenticator-app/auth/user"},
     {vhost_path,    "http://my-authenticator-app/auth/vhost"},
     {resource_path, "http://my-authenticator-app/auth/resource"}]}].
-</pre>      
-
+</pre>
 
           <p>
             The following example configures RabbitMQ to use internal
             database for authentication and <a
             href="https://github.com/gotthardp/rabbitmq-auth-backend-ip-range">source
             IP range backend</a> for authorisation:
           </p>
-
+
+<pre class="example">
+# rabbitmq.conf
+#
+auth_backends.1.authn = internal
+# uses module name because this backend is from a 3rd party
+auth_backends.1.authz = rabbit_auth_backend_ip_range
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
 <pre class="example">
 [{rabbit, [
             {auth_backends, [{rabbit_auth_backend_internal, rabbit_auth_backend_ip_range}]}
@@ -341,6 +414,16 @@ limitations under the License.
         The following example configures RabbitMQ to use <a href="/ldap.html">LDAP backend</a>
         for authentication and but internal backend for authorisation:
       </p>
+
+<pre class="example">
+# rabbitmq.conf
+#
+auth_backends.1.authn = ldap
+auth_backends.1.authz = internal
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
 <pre class="example">
 [{rabbit, [
             {auth_backends, [{rabbit_auth_backend_ldap, rabbit_auth_backend_internal}]
@@ -357,17 +440,23 @@ limitations under the License.
         a second attempt is made using only the internal database:
       </p>
 
+<pre class="example">
+# rabbitmq.conf
+#
+auth_backends.1.authn = ldap
+auth_backends.1.authz = internal
+auth_backends.2       = internal
+</pre>
+
+          Or, in the <a href="/configure.html#erlang-term-config-file">classic config format</a>:
+
 <pre class="example">
 [{rabbit, [
             {auth_backends, [{rabbit_auth_backend_ldap, rabbit_auth_backend_internal},
-                             rabbit_auth_backend_internal]
+                             rabbit_auth_backend_internal]}
           ]
  }].
-</pre>      
-        </doc:subsection>
-
-        <doc:subsection name="">
-          <doc:heading></doc:heading>
+</pre>
         </doc:subsection>
       </doc:section>
   </body>