path: root/qpid/doc/book/src/cpp-broker/Security.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.

-->
<section id="chap-Messaging_User_Guide-Security">
	<title>Security</title>
	 <para>
		This chapter describes how authentication, rule-based authorization, encryption, and digital signing can be accomplished using Qpid. Authentication is the process of verifying the identity of a user; in Qpid, this is done using the SASL framework. Rule-based authorization is a mechanism for specifying the actions that each user is allowed to perform; in Qpid, this is done using an Access Control List (ACL) that is part of the Qpid broker. Encryption is used to ensure that data is not transferred in a plain-text format that could be intercepted and read. Digital signatures provide proof that a given message was sent by a known sender. Encryption and signing are done using SSL (they can also be done using SASL, but SSL provides stronger encryption).
	</para>
	 <section id="sect-Messaging_User_Guide-Security-User_Authentication">
		<title>User Authentication</title>
		 <para>
			AMQP uses Simple Authentication and Security Layer (SASL) to authenticate client connections to the broker. SASL is a framework that supports a variety of authentication methods. For secure applications, we suggest <command>CRAM-MD5</command>, <command>DIGEST-MD5</command>, or <command>GSSAPI</command>. The <command>ANONYMOUS</command> method is not secure. The <command>PLAIN</command> method is secure only when used together with SSL.
		</para>
		 <para>
			Both the Qpid broker and Qpid clients use the <ulink url="http://cyrusimap.web.cmu.edu/">Cyrus SASL library</ulink>, a full-featured authentication framework, which offers many configuration options. This section shows how to configure users for authentication with SASL, which is sufficient when using <command>SASL PLAIN</command>. If you are not using SSL, you should configure SASL to use <command>CRAM-MD5</command>, <command>DIGEST-MD5</command>, or <command>GSSAPI</command> (which provides Kerberos authentication). For information on configuring these and other options in SASL, see the Cyrus SASL documentation<!-- at <filename>/usr/share/doc/cyrus-sasl-lib-2.1.22/index.html</filename> for &RHEL5; or <filename>/usr/share/doc/cyrus-sasl-2.1.19/index.html</filename> for &RHEL4;-->.
		</para>
		 <important>
			<title>Important</title>
			 <para>
				The <command>SASL PLAIN</command> method sends passwords in cleartext, and is vulnerable to man-in-the-middle attacks unless SSL (Secure Socket Layer) is also used (see <xref linkend="sect-Messaging_User_Guide-Security-Encryption_using_SSL" />).
			</para>
			 <para>
				If you are not using SSL, we recommend that you disable <command>PLAIN</command> authentication in the broker.
			</para>

		</important>
		 <para>
			The Qpid broker uses the <command>auth yes|no</command> option to determine whether to use SASL authentication. Turn on authentication by setting <command>auth</command> to <command>yes</command> in <filename>/etc/qpidd.conf</filename>:
		</para>

<programlisting>
# /etc/qpidd.conf
#
# Set auth to &#39;yes&#39; or &#39;no&#39;

auth=yes
</programlisting>
		 <section id="sect-Messaging_User_Guide-User_Authentication-Configuring_SASL">
			<title>Configuring SASL</title>
			 <para>
				On Linux systems, the SASL configuration file is generally found in <filename>/etc/sasl2/qpidd.conf</filename> <!-- for &RHEL5; and-->or <filename>/usr/lib/sasl2/qpidd.conf</filename><!-- for &RHEL4;-->.
			</para>
			 <para>
				The SASL database contains user names and passwords for SASL. In SASL, a user may be associated with a <firstterm>realm</firstterm>. The Qpid broker authenticates users in the <command>QPID</command> realm by default, but it can be set to a different realm using the <command>realm</command> option:
			</para>

<programlisting>
# /etc/qpidd.conf
#
# Set the SASL realm using &#39;realm=&#39;

auth=yes
realm=QPID
</programlisting>
			 <para>
				The SASL database is installed at <filename>/var/lib/qpidd/qpidd.sasldb</filename>; initially, it has one user named <command>guest</command> in the <command>QPID</command> realm, and the password for this user is <command>guest</command>.
			</para>
			 <note>
				<title>Note</title>
				 <para>
					The user database is readable only by the <systemitem class="username">qpidd</systemitem> user. When run as a daemon, Qpid always runs as the <systemitem class="username">qpidd</systemitem> user. If you start the broker from a user other than the <systemitem class="username">qpidd</systemitem> user, you will need to either reconfigure SASL or turn authentication off.
				</para>

			</note>
			 <important>
				<title>Important</title>
				 <para>
					The SASL database stores user names and passwords in plain text. If it is compromised so are all of the passwords that it stores. This is the reason that the <systemitem class="username">qpidd</systemitem> user is the only user that can read the database. If you modify permissions, be careful not to expose the SASL database.
				</para>

			</important>
			 <para>
				Add new users to the database by using the <command>saslpasswd2</command> command, which specifies a realm and a user ID. A user ID takes the form <command><replaceable>user-id</replaceable>@<replaceable>domain</replaceable>.</command>.
			</para>

<screen># saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <replaceable>realm</replaceable> <replaceable>new_user_name</replaceable></screen>
			 <para>
				To list the users in the SASL database, use <command>sasldblistusers2</command>:
			</para>

<screen># sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
</screen>
			 <para>
				If you are using <command>PLAIN</command> authentication, users who are in the database can now connect with their user name and password. This is secure only if you are using SSL. If you are using a more secure form of authentication, please consult your SASL documentation for information on configuring the options you need.
			</para>

		</section>

		 <section id="sect-Messaging_User_Guide-User_Authentication-Kerberos">
			<title>Kerberos</title>
			 <para>
				Both the Qpid broker and Qpid users are &#39;principals&#39; of the Kerberos server, which means that they are both clients of the Kerberos authentication services.
			</para>
			 <para>
				To use Kerberos, both the Qpid broker and each Qpid user must be authenticated on the Kerberos server:
			</para>
			 <procedure>
				<step>
					<para>
						Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client:
					</para>

<screen>$ sudo yum install cyrus-sasl-gssapi krb5-workstation</screen>

				</step>
				 <step>
					<para>
						Make sure that the Qpid broker is registered in the Kerberos database.
					</para>
					 <para>
						Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format <literal>primary/instance@REALM</literal>. For a Qpid broker, the primary is <literal>qpidd</literal>, the instance is the fully qualified domain name, which you can obtain using <command>hostname --fqdn</command>, and the REALM is the Kerberos domain realm. By default, this realm is <literal>QPID</literal>, but a different realm can be specified in qpid.conf, e.g.:
<screen>realm=EXAMPLE.COM</screen>

					</para>
					 <para>
						For instance, if the fully qualified domain name is <literal>dublduck.example.com</literal> and the Kerberos domain realm is <literal>EXAMPLE.COM</literal>, then the principal name is <literal>qpidd/dublduck.example.com@EXAMPLE.COM</literal>.
					</para>
					 <para>
						The following script creates a principal for qpidd:
					</para>

<programlisting>
FDQN=`hostname --fqdn`
REALM=&#34;EXAMPLE.COM&#34;
kadmin -r $REALM  -q &#34;addprinc -randkey -clearpolicy qpidd/$FQDN&#34;
</programlisting>
					 <para>
						Now create a Kerberos keytab file for the Qpid broker. The Qpid broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access:
					</para>

<programlisting>
QPIDD_GROUP=&#34;qpidd&#34;
kadmin -r $REALM  -q &#34;ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM&#34;
chmod g+r /etc/qpidd.keytab
chgrp $QPIDD_GROUP /etc/qpidd.keytab
</programlisting>
					 <para>
						The default location for the keytab file is <filename>/etc/krb5.keytab</filename>. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file, e.g.:
					</para>

<programlisting>
export KRB5_KTNAME=/etc/qpidd.keytab
</programlisting>
					 <para>
						If this is correctly configured, you can now enable kerberos support on the Qpid broker by setting the <varname>auth</varname> and <varname>realm</varname> options in <filename>/etc/qpidd.conf</filename>:
					</para>

<programlisting>
# /etc/qpidd.conf
auth=yes
realm=EXAMPLE.COM
</programlisting>
					 <para>
						Restart the broker to activate these settings.
					</para>

				</step>
				 <step>
					<para>
						Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed:
					</para>

<screen>$ kinit user@REALM.COM</screen>

				</step>

			</procedure>

			 <para>
				Java JMS clients require a few additional steps.
			</para>
			 <procedure>
				<step>
					<para>
						The Java JVM must be run with the following arguments:
					</para>
					 <variablelist>
						<varlistentry>
							<term>-Djavax.security.auth.useSubjectCredsOnly=false</term>
							 <listitem>
								<para>
									Forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the &#34;subject&#34; that owns the current thread.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term>-Djava.security.auth.login.config=myjas.conf</term>
							 <listitem>
								<para>
									Specifies the jass configuration file. Here is a sample JASS configuration file:
								</para>

<programlisting>
com.sun.security.jgss.initiate {
    com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};
</programlisting>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term>-Dsun.security.krb5.debug=true</term>
							 <listitem>
								<para>
									Enables detailed debug info for troubleshooting
								</para>

							</listitem>

						</varlistentry>

					</variablelist>

				</step>
				 <step>
					<para>
						The client&#39;s Connection URL must specify the following Kerberos-specific broker properties:
					</para>
					 <itemizedlist>
						<listitem>
							<para>
								<varname>sasl_mechs</varname> must be set to <literal>GSSAPI</literal>.
							</para>

						</listitem>
						 <listitem>
							<para>
								<varname>sasl_protocol</varname> must be set to the principal for the qpidd broker, e.g. <literal>qpidd</literal>/
							</para>

						</listitem>
						 <listitem>
							<para>
								<varname>sasl_server</varname> must be set to the host for the SASL server, e.g. <literal>sasl.com</literal>.
							</para>

						</listitem>

					</itemizedlist>
					 <para>
						Here is a sample connection URL for a Kerberos connection:
					</para>

<screen>amqp://guest@clientid/testpath?brokerlist=&#39;tcp://localhost:5672?sasl_mechs=&#39;GSSAPI&#39;&amp;sasl_protocol=&#39;qpidd&#39;&amp;sasl_server=&#39;&#60;server-host-name&#62;&#39;&#39;</screen>

				</step>

			</procedure>
<!--
			 <para>
				Please refer to the following documentation for more detail on using Kerberos:
			</para>
			 <variablelist>
				<varlistentry>
					<term>RHEL5</term>
					 <listitem>
						<para>
							<ulink url="http://www.redhat.com/docs/manuals/enterprise/RHEL-5-manual/Deployment_Guide-en-US/ch-kerberos.html"> Red Hat Enterprise Linux 5: Deployment Guide </ulink>
						</para>

					</listitem>

				</varlistentry>
				 <varlistentry>
					<term>RHEL4</term>
					 <listitem>
						<para>
							<ulink url="http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/ref-guide/ch-kerberos.html"> Red Hat Enterprise Linux 4: Reference Guide </ulink>
						</para>

					</listitem>

				</varlistentry>
				 <varlistentry>
					<term>Java</term>
					 <listitem>
						<para>
							<ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jgss/tutorials/index.html"> Introduction to JAAS and Java GSS-API Tutorials </ulink>
						</para>

					</listitem>

				</varlistentry>

			</variablelist>
            -->

		</section>


	</section>

         <!--          ###################################################          --> <section id="sect-Messaging_User_Guide-Security-Authorization">
                <title>Authorization</title>
                 <para>
                   In Qpid, Authorization specifies which actions can be performed by each authenticated user using an Access Control List (ACL).
                 </para>
                 <para>
                   Use the <command>--acl-file</command> command to load the access control list. The filename should have a <filename>.acl</filename> extension:
                </para>

<screen>
    $ qpidd --acl-file <replaceable>./aclfilename.acl</replaceable></screen>
                 <para>
                        Each line in an ACL file grants or denies specific rights to a user. If the last line in an ACL file is <literal>acl deny all all</literal>, the ACL uses <firstterm>deny mode</firstterm>, and only those rights that are explicitly allowed are granted:
                </para>

<programlisting>
    acl allow rajith@QPID all all
    acl deny all all
</programlisting>
                 <para>
                        On this server, <literal>rajith@QPID</literal> can perform any action, but nobody else can. Deny mode is the default, so the previous example is equivalent to the following ACL file:
                </para>

<programlisting>
    acl allow rajith@QPID all all
</programlisting>
                 <para>
                   Alternatively the ACL file may use <firstterm>allow mode</firstterm> by placing:
                </para>
<programlisting>
    acl allow all all
</programlisting>
                 <para>
                        as the final line in the ACL file. In <emphasis>allow mode</emphasis> all actions by all users are allowed unless otherwise denied by specific ACL rules.
                        The ACL rule which selects <emphasis>deny mode</emphasis> or <emphasis>allow mode</emphasis> must be the last line in the ACL rule file.
                </para>
                 <para>
                        ACL syntax allows fine-grained access rights for specific actions:
                </para>

<programlisting>
    acl allow carlt@QPID create exchange name=carl.*
    acl allow fred@QPID create all
    acl allow all consume queue
    acl allow all bind exchange
    acl deny all all
</programlisting>
                 <para>
                        An ACL file can define user groups, and assign permissions to them:
                </para>

<programlisting>
    group admin ted@QPID martin@QPID
    acl allow admin create all
    acl deny all all
</programlisting>
                 <para>
                        An ACL file can define per user connection and queue quotas:
                </para>

<programlisting>
    group admin ted@QPID martin@QPID
    group blacklist usera@qpid userb@qpid
    quota connections 10 admin
    quota connections  5 all
    quota connections  0 blacklist
    quota queues      50 admin
    quota queues       5 all
    quota queues       1 test@qpid
</programlisting>

                 <para>
                        Performance Note: Most ACL queries are performed infrequently. The overhead associated with
                        ACL passing an allow or deny decision on the creation of a queue is negligible
                        compared to actually creating and using the queue. One notable exception is the <command>publish exchange</command>
                        query. ACL files with no <emphasis>publish exchange</emphasis> rules are noted and the broker short circuits the logic
                        associated with the per-messsage <emphasis>publish exchange</emphasis> ACL query.
                        However, if an ACL file has any <emphasis>publish exchange</emphasis> rules
                        then the broker is required to perform a <emphasis>publish exchange</emphasis> query for each message published.
                        Users with performance critical applications are encouraged to structure exchanges, queues, and bindings so that
                        the <emphasis>publish exchange</emphasis> ACL rules are unnecessary.
                </para>

                 <!--          ########          --> <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntax">
                        <title>ACL Syntax</title>
                         <para>
                                ACL rules follow this syntax:
<programlisting><![CDATA[
aclline = ( comment | aclspec | groupspec | quotaspec )

comment = "#" [ STRING ]

aclspec = "acl" permission ( groupname | name | "all" )
          ( action | "all" ) [ ( object | "all ) [ ( property "=" STRING )* ] ]

groupspec = "group" groupname ( name )* [ "\" ]

groupcontinuation = ( name )* [ "\" ]

quotaspec = "quota" ( "connections" | "queues" ) NUMBER ( groupname | name | "all" )*

name = ( ALPHANUMERIC | "-" | "_" | "." | "@" | "/" ) [ ( ALPHANUMERIC | "-" | "_" | "." | "@" | "/" )* ]

groupname = ( ALPHANUMERIC | "-" | "_" ) [ ( ALPHANUMERIC | "-" | "_" )* ]

permission = "allow" | "allow-log" | "deny" | "deny-log"

action = "consume" | "publish" | "create" | "access" |
         "bind"    | "unbind"  | "delete" | "purge"  |
         "update"

object = "queue"  | "exchange" | "broker"     | "link" |
         "method" | "query"    | "connection"

property =  "name" | "durable" | "routingkey" | "autodelete" |
            "exclusive" | "type" | "alternate" | "queuename"  |
            "exchangename" | "schemapackage" | "schemaclass" |
            "policytype" | "paging" |
            "queuemaxsizelowerlimit"  | "queuemaxsizeupperlimit" |
            "queuemaxcountlowerlimit" | "queuemaxcountupperlimit" |
            "filemaxsizelowerlimit"   | "filemaxsizeupperlimit" |
            "filemaxcountlowerlimit"  | "filemaxcountupperlimit" |
            "pageslowerlimit"         | "pagesupperlimit" |
            "pagefactorlowerlimit"    | "pagefactorupperlimit"
]]></programlisting>

                                 ACL rules can also include a single object name (or the keyword <parameter>all</parameter>) and one or more property name value pairs in the form <command>property=value</command>
                        </para>
                         <para>
                                The following tables show the possible values for <command>permission</command>, <command>action</command>, <command>object</command>, and <command>property</command> in an ACL rules file.
                         </para>
                         <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rules_permission">
                           <title>ACL Rules: permission</title>
                           <tgroup cols="2">
                             <tbody>
                               <row>
                                 <entry>
                                   <command>allow</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Allow the action <!--          ### rule => the action          -->
                                   </para>
                                 </entry>
                                 </row>
                                 <row>
                                   <entry>
                                     <command>allow-log</command>
                                   </entry>
                                   <entry>
                                     <para>
                                       Allow the action and log the action in the event log
                                     </para>
                                   </entry>
                                 </row>
                                 <row>
                                   <entry>
                                     <command>deny</command>
                                   </entry>
                                   <entry>
                                     <para>
                                       Deny the action
                                     </para>
                                   </entry>
                                 </row>
                                 <row>
                                   <entry>
                                     <command>deny-log</command>
                                   </entry>
                                   <entry>
                                     <para>
                                       Deny the action and log the action in the event log
                                     </para>
                                   </entry>
                                 </row>
                             </tbody>
                           </tgroup>
                         </table>
                         <!--          Actions          --> <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesaction">
                           <title>ACL Rules: action</title>
                           <tgroup cols="2">
                             <tbody>
                               <row>
                                 <entry>
                                   <command>access</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Accessing or reading an object
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>bind</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Associating a queue to an exchange with a routing key.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>consume</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Using an object
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>create</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Creating an object.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>delete</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Deleting an object.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>move</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Moving messages between queues.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>publish</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Authenticating an incoming message.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>purge</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Purging a queue.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>redirect</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Redirecting messages between queues
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>reroute</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Rerouting messages from a queue to an exchange
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>unbind</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Disassociating a queue from an exchange with a routing key.
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>update</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Changing a broker configuration setting.
                                   </para>
                                 </entry>
                               </row>
                             </tbody>
                           </tgroup>
                         </table>
                         <!--          object types          --> <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesobject">
                           <title>ACL Rules:object</title>
                           <tgroup cols="2">
                             <tbody>
                               <row>
                                 <entry>
                                   <command>broker</command>
                                 </entry>
                                 <entry>
                                   <para>
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>connection</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Incoming TCP/IP connection
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>exchange</command>
                                 </entry>
                                 <entry>
                                   <para>
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>link</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     A federation or inter-broker link
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>method</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Management method
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>query</command>
                                 </entry>
                                 <entry>
                                   <para>
                                     Management query of an object or class
                                   </para>
                                 </entry>
                               </row>
                               <row>
                                 <entry>
                                   <command>queue</command>
                                 </entry>
                                 <entry>
                                   <para>
                                   </para>
                                 </entry>
                               </row>
                             </tbody>
                           </tgroup>
                         </table>
                         <!--
        <para>
          Wild cards can be used on properties that are a string. The following rule properties are supported:          -->
                         <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesproperty">
                           <title>ACL Rules: property</title>
                           <tgroup cols="4">
                             <thead>
                               <row>
                                 <entry>Property</entry>
                                 <entry>Type</entry>
                                 <entry>Description</entry>
                                 <entry>Usage</entry>
                               </row>
                             </thead>
                             <tbody>
                               <row>
                                 <entry> <command>name</command> </entry>
                                 <entry>String</entry>
                                 <entry>Rule refers to objects with this name. When 'name' is blank or absent then the rule
                                 applies to all objects of the given type.</entry>
                                 <entry></entry>
                               </row>
                               <row>
                                 <entry> <command>alternate</command> </entry>
                                 <entry>String</entry>
                                 <entry>Name of an alternate exchange</entry>
                                 <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</entry>
                               </row>
                               <row>
                                 <entry> <command>autodelete</command> </entry>
                                 <entry>Boolean</entry>
                                 <entry>Indicates whether or not the object gets deleted when the connection that created it is closed</entry>
                                 <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>durable</command> </entry>
                                 <entry>Boolean</entry>
                                 <entry>Rule applies to durable objects</entry>
                                 <entry>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</entry>
                               </row>
                               <row>
                                 <entry> <command>exchangename</command> </entry>
                                 <entry>String</entry>
                                 <entry>Name of the exchange to which queue's entries are routed</entry>
                                 <entry>REROUTE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>filemaxcountlowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for file.max_count (files)</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>filemaxcountupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for file.max_count (files)</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>filemaxsizelowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for file.max_size (64kb pages)</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>filemaxsizeupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for file.max_size (64kb pages)</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>host</command> </entry>
                                 <entry>String</entry>
                                 <entry>Target TCP/IP host or host range for create connection rules</entry>
                                 <entry>CREATE CONNECTION</entry>
                               </row>
                               <row>
                                 <entry> <command>exclusive</command> </entry>
                                 <entry>Boolean</entry>
                                 <entry>Indicates the presence of an <parameter>exclusive</parameter> flag</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>pagefactorlowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for size of a page in paged queue</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>pagefactorupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for size of a page in paged queue</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>pageslowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for number of paged queue pages in memory</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>pagesupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for number of paged queue pages in memory</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>paging</command> </entry>
                                 <entry>Boolean</entry>
                                 <entry>Indicates if the queue is a paging queue</entry>
                                 <entry>CREATE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>policytype</command> </entry>
                                 <entry>String</entry>
                                 <entry>"ring", "self-destruct", "reject"</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>queuename</command> </entry>
                                 <entry>String</entry>
                                 <entry>Name of the target queue</entry>
                                 <entry>ACCESS EXCHANGE, BIND EXCHANGE, MOVE QUEUE, UNBIND EXCHANGE</entry>
                               </row>
                               <row>
                                 <entry> <command>queuemaxsizelowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for queue.max_size (memory bytes)</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>queuemaxsizeupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for queue.max_size (memory bytes)</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>queuemaxcountlowerlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Minimum value for queue.max_count (messages)</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>queuemaxcountupperlimit</command> </entry>
                                 <entry>Integer</entry>
                                 <entry>Maximum value for queue.max_count (messages)</entry>
                                 <entry>CREATE QUEUE, ACCESS QUEUE</entry>
                               </row>
                               <row>
                                 <entry> <command>routingkey</command> </entry>
                                 <entry>String</entry>
                                 <entry>Specifies routing key</entry>
                                 <entry>BIND EXCHANGE, UNBIND EXCHANGE, ACCESS EXCHANGE, PUBLISH EXCHANGE</entry>
                               </row>
                               <row>
                                 <entry> <command>schemaclass</command> </entry>
                                 <entry>String</entry>
                                 <entry>QMF schema class name</entry>
                                 <entry>ACCESS METHOD, ACCESS QUERY</entry>
                               </row>
                               <row>
                                 <entry> <command>schemapackage</command> </entry>
                                 <entry>String</entry>
                                 <entry>QMF schema package name</entry>
                                 <entry>ACCESS METHOD</entry>
                               </row>
                               <row>
                                 <entry> <command>type</command> </entry>
                                 <entry>String</entry>
                                 <entry>Type of exchange, such as topic, fanout, or xml</entry>
                                 <entry>CREATE EXCHANGE, ACCESS EXCHANGE, DELETE EXCHANGE</entry>
                               </row>
                             </tbody>
                           </tgroup>
                         </table>

                         <section id="sect-Messaging_User_Guide-Authorization-ACL_ActionObjectPropertyTuples">
                           <title>ACL Action-Object-Property Combinations</title>
                           <para>
                             Not every ACL action is applicable to every ACL object. Furthermore, not every property may be
                             specified for every action-object pair. The following table lists the broker events
                             that trigger ACL lookups. Then for each event it lists the action, object, and properties
                             allowed in the lookup.
                           </para>
                           <para>
                             User-specified ACL rules constrain property sets to those that match one or more of
                             the action and object pairs. For example these rules are allowed:
                           </para>
<programlisting>
    acl allow all access exchange
    acl allow all access exchange name=abc
    acl allow all access exchange name=abc durable=true
</programlisting>
                           <para>
                             These rules could possibly match one or more of the broker lookups. However, this rule
                             is not allowed:
                           </para>
<programlisting>
    acl allow all access exchange queuename=queue1 durable=true
</programlisting>
                           <para>
                             Properties <emphasis>queuename</emphasis> and <emphasis>durable</emphasis>
                             are not in the list of allowed properties for any 'access exchange' lookup.
                             This rule would never match a broker lookup query and would never contribute to an
                             allow or deny decision.
                           </para>
                           <para>
                             For more information about matching ACL rules please refer to
                             <link linkend="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching">
                               ACL Rule Matching
                             </link>
                           </para>

                           <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties">
                             <title>Broker Lookup Events With Allowed Action, Object, and Properties</title>
                             <tgroup cols="4">
                               <thead>
                                 <row>
                                   <entry>Lookup Event</entry>
                                   <entry>Action</entry>
                                   <entry>Object</entry>
                                   <entry>Properties</entry>
                                 </row>
                               </thead>
                               <tbody>
                                 <row>
                                   <entry>User querying message timestamp setting </entry>
                                   <entry>access</entry>
                                   <entry>broker</entry>
                                   <entry></entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 protocol received 'query'     </entry>
                                   <entry>access</entry>
                                   <entry>exchange</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 query binding                 </entry>
                                   <entry>access</entry>
                                   <entry>exchange</entry>
                                   <entry>name queuename routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 exchange declare              </entry>
                                   <entry>access</entry>
                                   <entry>exchange</entry>
                                   <entry>name type alternate durable autodelete </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 exchange access                </entry>
                                   <entry>access</entry>
                                   <entry>exchange</entry>
                                   <entry>name type durable </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 node resolution                </entry>
                                   <entry>access</entry>
                                   <entry>exchange</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>Management method request               </entry>
                                   <entry>access</entry>
                                   <entry>method</entry>
                                   <entry>name schemapackage schemaclass </entry>
                                 </row>
                                 <row>
                                   <entry>Management agent method request         </entry>
                                   <entry>access</entry>
                                   <entry>method</entry>
                                   <entry>name schemapackage schemaclass </entry>
                                 </row>
                                 <row>
                                   <entry>Management agent query                  </entry>
                                   <entry>access</entry>
                                   <entry>query</entry>
                                   <entry>name schemaclass </entry>
                                 </row>
                                 <row>
                                   <entry>QMF 'query queue' method                </entry>
                                   <entry>access</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 query                         </entry>
                                   <entry>access</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 queue declare                 </entry>
                                   <entry>access</entry>
                                   <entry>queue</entry>
                                   <entry>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 queue access                   </entry>
                                   <entry>access</entry>
                                   <entry>queue</entry>
                                   <entry>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 node resolution                </entry>
                                   <entry>access</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 or QMF bind request           </entry>
                                   <entry>bind</entry>
                                   <entry>exchange</entry>
                                   <entry>name queuename routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 new outgoing link from exchange</entry>
                                   <entry>bind</entry>
                                   <entry>exchange</entry>
                                   <entry>name queuename routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 subscribe request             </entry>
                                   <entry>consume</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 new outgoing link from queue   </entry>
                                   <entry>consume</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>TCP/IP connection creation              </entry>
                                   <entry>create</entry>
                                   <entry>connection</entry>
                                   <entry>host </entry>
                                 </row>
                                 <row>
                                   <entry>Create exchange                         </entry>
                                   <entry>create</entry>
                                   <entry>exchange</entry>
                                   <entry>name type alternate durable autodelete </entry>
                                 </row>
                                 <row>
                                   <entry>Interbroker link creation               </entry>
                                   <entry>create</entry>
                                   <entry>link</entry>
                                   <entry></entry>
                                 </row>
                                 <row>
                                   <entry>Interbroker link creation               </entry>
                                   <entry>create</entry>
                                   <entry>link</entry>
                                   <entry></entry>
                                 </row>
                                 <row>
                                   <entry>Create queue                            </entry>
                                   <entry>create</entry>
                                   <entry>queue</entry>
                                   <entry>name alternate durable exclusive autodelete policytype paging pageslowerlimit pagesupperlimit pagefactorlowerlimit pagefactorupperlimit queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit filemaxcountlowerlimit filemaxcountupperlimit filemaxsizelowerlimit filemaxsizeupperlimit </entry>
                                 </row>
                                 <row>
                                   <entry>Delete exchange                         </entry>
                                   <entry>delete</entry>
                                   <entry>exchange</entry>
                                   <entry>name type alternate durable </entry>
                                 </row>
                                 <row>
                                   <entry>Delete queue                            </entry>
                                   <entry>delete</entry>
                                   <entry>queue</entry>
                                   <entry>name alternate durable exclusive autodelete policytype </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'move queue' request         </entry>
                                   <entry>move</entry>
                                   <entry>queue</entry>
                                   <entry>name queuename </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 0-10 received message processing   </entry>
                                   <entry>publish</entry>
                                   <entry>exchange</entry>
                                   <entry>name routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 establish sender link to queue </entry>
                                   <entry>publish</entry>
                                   <entry>exchange</entry>
                                   <entry>routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>AMQP 1.0 received message processing    </entry>
                                   <entry>publish</entry>
                                   <entry>exchange</entry>
                                   <entry>name routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'purge queue' request        </entry>
                                   <entry>purge</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'purge queue' request        </entry>
                                   <entry>purge</entry>
                                   <entry>queue</entry>
                                   <entry>name </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'redirect queue' request     </entry>
                                   <entry>redirect</entry>
                                   <entry>queue</entry>
                                   <entry>name queuename </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'reroute queue' request      </entry>
                                   <entry>reroute</entry>
                                   <entry>queue</entry>
                                   <entry>name exchangename </entry>
                                 </row>
                                 <row>
                                   <entry>Management 'unbind exchange' request    </entry>
                                   <entry>unbind</entry>
                                   <entry>exchange</entry>
                                   <entry>name queuename routingkey </entry>
                                 </row>
                                 <row>
                                   <entry>User modifying message timestamp setting</entry>
                                   <entry>update</entry>
                                   <entry>broker</entry>
                                   <entry></entry>
                                 </row>
                               </tbody>
                             </tgroup>
                           </table>
                         </section>
                       </section>

                 <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions">
                        <title>ACL Syntactic Conventions</title>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-comments">
                          <title>Comments</title>
                          <para>
                            <itemizedlist>
                              <listitem>
                                <para>
                                  A line starting with the <command>#</command> character is considered a comment and is ignored.
                                </para>
                              </listitem>
                              <listitem>
                                <para>
                                  Embedded comments and trailing comments are not allowed. The <command>#</command> is commonly found in routing keys and other AMQP literals which occur naturally in ACL rule specifications.
                                </para>
                              </listitem>
                            </itemizedlist>
                          </para>
                        </section>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-whitespace">
                          <title>White Space</title>
                          <itemizedlist>
                            <listitem>
                              <para>
                                Empty lines and lines that contain only whitespace (' ', '\f', '\n', '\r', '\t', '\v') are ignored.
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Additional whitespace between and after tokens is allowed.
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Group and Acl definitions must start with <command>group</command> and <command>acl</command> respectively and with no preceding whitespace.
                              </para>
                            </listitem>
                          </itemizedlist>
                        </section>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-characterset">
                          <title>Character Set</title>
                          <itemizedlist>
                            <listitem>
                              <para>
                                ACL files use 7-bit ASCII characters only
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Group names may contain only
                                <itemizedlist>
                                  <listitem><command>[a-z]</command></listitem>
                                  <listitem><command>[A-Z]</command></listitem>
                                  <listitem><command>[0-9]</command></listitem>
                                  <listitem><command>'-'</command> hyphen</listitem>
                                  <listitem><command>'_'</command> underscore</listitem>
                                </itemizedlist>
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Individual user names may contain only
                                <itemizedlist>
                                  <listitem><command>[a-z]</command></listitem>
                                  <listitem><command>[A-Z]</command></listitem>
                                  <listitem><command>[0-9]</command></listitem>
                                  <listitem><command>'-'</command> hyphen</listitem>
                                  <listitem><command>'_'</command> underscore</listitem>
                                  <listitem><command>'.'</command> period</listitem>
                                  <listitem><command>'@'</command> ampersand</listitem>
                                  <listitem><command>'/'</command> slash</listitem>
                                </itemizedlist>
                              </para>
                            </listitem>
                          </itemizedlist>
                        </section>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-casesensitivity">
                          <title>Case Sensitivity</title>
                          <itemizedlist>
                            <listitem>
                              <para>
                                All tokens are case sensitive. <parameter>name1</parameter> is not the same as <parameter>Name1</parameter> and <parameter>create</parameter> is not the same as <parameter>CREATE</parameter>.
                              </para>
                            </listitem>
                          </itemizedlist>
                        </section>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linecontinuation">
                          <title>Line Continuation</title>
                          <itemizedlist>
                            <listitem>
                              <para>
                                Group lists can be extended to the following line by terminating the line with the <command>'\'</command> character. No other ACL file lines may be continued.
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Group specification lines may be continued only after the group name or any of the user names included in the group. See example below.
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                Lines consisting solely of a <command>'\'</command> character are not permitted.
                              </para>
                            </listitem>
                            <listitem>
                              <para>
                                The <command>'\'</command> continuation character is recognized only if it is the last character in the line. Any characters after the <command>'\'</command> are not permitted.
                              </para>
                            </listitem>
                          </itemizedlist>
<programlisting><![CDATA[
    #
    # Examples of extending group lists using a trailing '\' character
    #
    group group1 name1 name2 \
    name3 name4 \
    name5

    group group2 \
                 group1 \
                 name6
    #
    # The following are illegal:
    #
    # '\' must be after group name
    #
    group \
          group3 name7 name8
    #
    # No empty extension line
    #
    group group4 name9 \
                       \
                 name10
]]></programlisting>

                        </section>
                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linelength">
                          <title>Line Length</title>
                          <itemizedlist>
                            <listitem>
                              <para>
                                ACL file lines are limited to 1024 characters.
                              </para>
                            </listitem>
                          </itemizedlist>
                        </section>


                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords">
                          <title>ACL File Keywords</title>
                          ACL reserves several words for convenience and for context sensitive substitution.

                          <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-all">
                            <title>The <command>all</command> Keyword</title>
                            The keyword <command>all</command> is reserved. It may be used in ACL rules to match all individuals and groups, all actions, or all objects.
                            <itemizedlist>
                              <listitem>acl allow all create queue</listitem>
                              <listitem>acl allow bob@QPID all queue</listitem>
                              <listitem>acl allow bob@QPID create all</listitem>
                            </itemizedlist>
                          </section>

                          <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-userdomain">
                            <title>User Name and Domain Name Keywords</title>
                            <para>
                              In the C++ Broker 0.20 a simple set of user name and domain name substitution variable keyword tokens is defined. This provides administrators with an easy way to describe private or shared resources.
                            </para>
                            <para>
                              Symbol substitution is allowed in the ACL file anywhere that text is supplied for a property value.
                            </para>
                            <para>
                              In the following table an authenticated user named bob.user@QPID.COM has his substitution keywords expanded.

                              <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_UsernameSubstitution">
                                <title>ACL User Name and Domain Name Substitution Keywords</title>
                                <tgroup cols="2">
                                  <thead>
                                    <row>
                                      <entry>Keyword</entry>
                                      <entry>Expansion</entry>
                                    </row>
                                  </thead>
                                  <tbody>
                                    <row>
                                      <entry> <command>${userdomain}</command> </entry>
                                      <entry>bob_user_QPID_COM</entry>
                                    </row>
                                    <row>
                                      <entry> <command>${user}</command> </entry>
                                      <entry>bob_user</entry>
                                    </row>
                                    <row>
                                      <entry> <command>${domain}</command> </entry>
                                      <entry>QPID_COM</entry>
                                    </row>
                                  </tbody>
                                </tgroup>
                              </table>
                            </para>

                            <para>
                              <itemizedlist>
                                <listitem>
                                  The original user name has the period “.” and ampersand “@” characters translated into underscore “_”. This allows substitution to work when the substitution keyword is used in a routingkey in the Acl file.
                                </listitem>
                                <listitem>
                                  The Acl processing matches ${userdomain} before matching either ${user} or ${domain}. Rules that specify the combination ${user}_${domain} will never match.
                                </listitem>
                              </itemizedlist>
                            </para>

<programlisting><![CDATA[
  # Example:
  #
  # Administrators can set up Acl rule files that allow every user to create a
  # private exchange, a private queue, and a private binding between them.
  # In this example the users are also allowed to create private backup exchanges,
  # queues and bindings. This effectively provides limits to user's exchange,
  # queue, and binding creation and guarantees that each user gets exclusive
  # access to these resources.
  #
  #
  # Create primary queue and exchange:
  #
  acl allow all create  queue    name=$\{user}-work alternate=$\{user}-work2
  acl deny  all create  queue    name=$\{user}-work alternate=*
  acl allow all create  queue    name=$\{user}-work
  acl allow all create  exchange name=$\{user}-work alternate=$\{user}-work2
  acl deny  all create  exchange name=$\{user}-work alternate=*
  acl allow all create  exchange name=$\{user}-work
  #
  # Create backup queue and exchange
  #
  acl deny  all create  queue    name=$\{user}-work2 alternate=*
  acl allow all create  queue    name=$\{user}-work2
  acl deny  all create  exchange name=$\{user}-work2 alternate=*
  acl allow all create  exchange name=$\{user}-work2
  #
  # Bind/unbind primary exchange
  #
  acl allow all bind   exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  acl allow all unbind exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  #
  # Bind/unbind backup exchange
  #
  acl allow all bind   exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  acl allow all unbind exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  #
  # Access primary exchange
  #
  acl allow all access exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  #
  # Access backup exchange
  #
  acl allow all access exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  #
  # Publish primary exchange
  #
  acl allow all publish exchange name=$\{user}-work routingkey=$\{user}
  #
  # Publish backup exchange
  #
  acl allow all publish exchange name=$\{user}-work2 routingkey=$\{user}
  #
  # deny mode
  #
  acl deny all all
]]></programlisting>
                          </section>

                        </section>

                        <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards">
                          <title>Wildcards</title>
                          ACL privides two types of wildcard matching to provide flexibility in writing rules.

                          <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-asterisk">
                            <title>Property Value Wildcard</title>
                            <para>
                              Text specifying a property value may end with a single trailing <command>*</command> character.
                              This is a simple wildcard match indicating that strings which match up to that point are matches for the ACL property rule.
                              An ACL rule such as
                            </para>
                            <para>
                              <programlisting>    acl allow bob@QPID create queue name=bob*</programlisting>
                            </para>
                            <para>
                              allow user bob@QPID to create queues named bob1, bob2, bobQueue3, and so on.
                            </para>
                          </section>

                          <section id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-topickey">
                            <title>Topic Routing Key Wildcard</title>
                            <para>
                              In the C++ Broker 0.20 the logic governing the ACL Match has changed for each ACL rule that contains a routingkey property.
                              The routingkey property is matched according to Topic Exchange match logic the broker uses when it distributes messages published to a topic exchange.
                            </para>
                            <para>
                              Routing keys are hierarchical where each level is separated by a period:
                              <itemizedlist>
                                <listitem>weather.usa</listitem>
                                <listitem>weather.europe.germany</listitem>
                                <listitem>weather.europe.germany.berlin</listitem>
                                <listitem>company.engineering.repository</listitem>
                              </itemizedlist>
                            </para>
                            <para>
                              Within the routing key hierarchy two wildcard characters are defined.
                              <itemizedlist>
                                <listitem><command>*</command> matches one field</listitem>
                                <listitem><command>#</command> matches zero or more fields</listitem>
                              </itemizedlist>
                            </para>
                            <para>
                              Suppose an ACL rule file is:
                            </para>
                            <para>
                              <programlisting>
    acl allow-log uHash1@COMPANY publish exchange name=X routingkey=a.#.b
    acl deny all all
                              </programlisting>
                            </para>
                            <para>
                              When user uHash1@COMPANY attempts to publish to exchange X the ACL will return these results:

                              <table id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_TopicExchangeMatch">
                                <title>Topic Exchange Wildcard Match Examples</title>
                                <tgroup cols="2">
                                  <thead>
                                    <row>
                                      <entry>routingkey in publish to exchange X</entry>
                                      <entry>result</entry>
                                    </row>
                                  </thead>
                                  <tbody>
                                    <row>
                                      <entry> <command>a.b</command> </entry>
                                      <entry>allow-log</entry>
                                    </row>
                                    <row>
                                      <entry> <command>a.x.b</command> </entry>
                                      <entry>allow-log</entry>
                                    </row>
                                    <row>
                                      <entry> <command>a.x.y.zz.b</command> </entry>
                                      <entry>allow-log</entry>
                                    </row>
                                    <row>
                                      <entry> <command>a.b.</command> </entry>
                                      <entry>deny</entry>
                                    </row>
                                    <row>
                                      <entry> <command>q.x.b</command> </entry>
                                      <entry>deny</entry>
                                    </row>
                                  </tbody>
                                </tgroup>
                              </table>

                            </para>
                          </section>

                        </section>



                      </section>

                 <section id="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching">
                        <title>ACL Rule Matching</title>
                         <para>
                           The minimum matching criteria for ACL rules are:
                           <itemizedlist>
                             <listitem>An actor (individually named or group member)</listitem>
                             <listitem>An action</listitem>
                             <listitem>An object</listitem>
                           </itemizedlist>
                         </para>
                         <para>
                           If a rule does not match the minimum criteria then that rule does not control the ACL allow or deny decision.
                         </para>
                         <para>
                           ACL rules optionally specify object names and property name=value pairs. If an ACL rule specifies an object name or property values than all of them must match to cause the rule to match.
                         </para>
                         <para>
                           The following illustration shows how ACL rules are processed to find matching rules.
<programlisting><![CDATA[
    # Example of rule matching
    #
    # Using this ACL file content:

    (1)  acl deny bob create exchange name=test durable=true passive=true
    (2)  acl deny bob create exchange name=myEx type=direct
    (3)  acl allow all all

    #
    # Lookup 1. id:bob action:create objectType:exchange name=test
    #           {durable=false passive=false type=direct alternate=}
    #
    # ACL Match Processing:
    #  1. Rule 1 passes minimum criteria with user bob, action create,
    #     and object exchange.
    #  2. Rule 1 matches name=test.
    #  3. Rule 1 does not match the rule's durable=true with the requested
    #     lookup of durable=false.
    #  4. Rule 1 does not control the decision and processing continues
    #     to Rule 2.
    #  5. Rule 2 passes minimum criteria with user bob, action create,
    #     and object exchange.
    #  6. Rule 2 does not match the rule's name=myEx with the requested
    #     lookup of name=test.
    #  7. Rule 2 does not control the decision and processing continues
    #     to Rule 3.
    #  8. Rule 3 matches everything and the decision is 'allow'.
    #
    # Lookup 2. id:bob action:create objectType:exchange name=myEx
    #           {durable=true passive=true type=direct alternate=}
    #
    # ACL Match Processing:
    #  1. Rule 1 passes minimum criteria with user bob, action create,
    #     and object exchange.
    #  2. Rule 1 does not match the rule's name=test with the requested
    #     lookup of name=myEx.
    #  3. Rule 1 does not control the decision and processing continues
    #     to Rule 2.
    #  4. Rule 2 passes minimum criteria with user bob, action create,
    #     and object exchange.
    #  5. Rule 2 matches name=myEx.
    #  6. Rule 2 matches the rule's type=direct with the requested
    #     lookup of type=direct.
    #  7. Rule 2 is the matching rule and the decision is 'deny'.
    #
]]></programlisting>
                         </para>
                         <para>
                           Referring to <link linkend="tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties">ACL Properties Allowed for each Action and Object table</link> observe that some Action/Object pairs have different sets of allowed properties. For example different broker ACL lookups for <emphasis>access exchange</emphasis> have different property subsets.
                         </para>

<programlisting>
    [1] access exchange name
    [2] access exchange name type alternate durable autodelete
    [3] access exchange name queuename routingkey
    [4] access exchange name type durable
</programlisting>

                         <para>
                           If an ACL rule specifies the <emphasis>autodelete</emphasis> property then it can possibly match only the second case above. It can never match cases 1, 3, and 4 because the broker calls to ACL will not present the autodelete property for matching. To get proper matching the ACL rule must have only the properties of the intended lookup case.
                         </para>

<programlisting>
    acl allow bob access exchange alternate=other    ! may match pattern 2 only
    acl allow bob access exchange queuename=other    ! may match pattern 3 only
    acl allow bob access exchange durable=true       ! may match patterns 2 and 4 only
    acl deny  bob access exchange                    ! may match all patterns
</programlisting>

                 </section>

                 <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Permissions">
                        <title>Specifying ACL Permissions</title>
                         <para>
                           Now that we have seen the ACL syntax, we will provide representative examples and guidelines for ACL files.
                        </para>
                         <para>
                                Most ACL files begin by defining groups:
                        </para>

<programlisting>
    group admin ted@QPID martin@QPID
    group user-consume martin@QPID ted@QPID
    group group2 kim@QPID user-consume rob@QPID
    group publisher group2 \
    tom@QPID andrew@QPID debbie@QPID
</programlisting>
                         <para>
                                Rules in an ACL file grant or deny specific permissions to users or groups:
                        </para>

<programlisting>
    acl allow carlt@QPID create exchange name=carl.*
    acl allow rob@QPID create queue
    acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.rht.#
    acl allow user-consume create queue name=tmp.*

    acl allow publisher publish all durable=false
    acl allow publisher create queue name=RequestQueue
    acl allow consumer consume queue durable=true
    acl allow fred@QPID create all
    acl allow bob@QPID all queue
    acl allow admin all
    acl allow all consume queue
    acl allow all bind exchange
    acl deny all all
</programlisting>
                         <para>
                                In the previous example, the last line, <literal>acl deny all all</literal>, denies all authorizations that have not been specifically granted. This is the default, but it is useful to include it explicitly on the last line for the sake of clarity. If you want to grant all rights by default, you can specify <literal>acl allow all all</literal> in the last line.
                        </para>
                        <para>
                          ACL allows specification of conflicting rules. Be sure to specify the most specific rules first followed by more general rules. Here is an example:
                        </para>
                        <para>
<programlisting>
    group users alice@QPID bob@QPID charlie@QPID
    acl deny  charlie@QPID create queue
    acl allow users        create queue
    acl deny all all
</programlisting>
                        </para>
                        <para>
                          In this example users alice and bob would be able to create queues due to their membership in the users group. However, user charlie is denied from creating a queue despite his membership in the users group because a deny rule for him is stated before the allow rule for the users group.
                        </para>
                         <para>
                                Do not allow <parameter>guest</parameter> to access and log QMF management methods that could cause security breaches:
                        </para>

<programlisting>
    group allUsers guest@QPID
    ...
    acl deny-log allUsers create link
    acl deny-log allUsers access method name=connect
    acl deny-log allUsers access method name=echo
    acl allow all all
</programlisting>

                </section>
                <section id="sect-Messaging_User_Guide-Authorization-Auditing_ACL_Settings">
                  <title>Auditing ACL Settings</title>
                  <para>
                    The 0.30 C++ Broker ACL module provides a comprehensive set of run-time and debug logging checks.
                    The following example ACL file is used to illustrate working with the ACL module debugging features.
                  </para>
<programlisting>
   group x a@QPID b@QPID b2@QPID b3@QPID
   acl allow all delete broker
   acl allow all create queue name=abc
   acl allow all create queue exchangename=xyz
   acl allow all create connection host=1.1.1.1
   acl allow all access exchange alternate=abc queuename=xyz
   acl allow all access exchange queuename=xyz
   acl allow all access exchange alternate=abc
   acl allow a@qpid all all exchangename=123
   acl allow b@qpid all all
   acl allow all all
</programlisting>
                  <para>
                    When this file is loaded it will show the following (truncated, formatted) Info-level log.
                  </para>
<programlisting>
  notice ACL: Read file "/home/chug/acl/svn-acl.acl"
  warning ACL rule ignored: Broker never checks for rules with
                            action: 'delete' and object: 'broker'
  warning ACL rule ignored: Broker checks for rules with
                            action: 'create' and object: 'queue'
              but will never match with property set: { exchangename=xyz }
  warning ACL rule ignored: Broker checks for rules with
                            action: 'access' and object: 'exchange'
              but will never match with property set: { alternate=abc queuename=xyz }
  info ACL Plugin loaded
</programlisting>
                  <para>
                    Three of the rules are invalid. The first invalid rule is rejected because there are no rules
                    that specify 'delete broker' regardless of the properties. The other two rules are rejected
                    because the property sets in the ACL rule don't match any broker lookups.
                  </para>
                  <para>
                    The ACL module only issues a warning about these rules and continues to operate. Users upgrading
                    from previous versions should be concerned that these rules never had any effect and should fix
                    the rules to have the property sets needed to allow or deny the intended broker events.
                  </para>
                  <para>
                    The next illustration shows the Debug-level log. Debug log level includes information about
                    constructing the rule tables, expanding groups and keywords, connection and queue quotas, and
                    connection black and white lists.
                  </para>
<programlisting>
  notice ACL: Read file "/home/chug/acl/svn-acl.acl"
  debug ACL: Group list: 1 groups found:
  debug ACL:   "x": a@QPID b2@QPID b3@QPID b@QPID
  debug ACL: name list: 7 names found:
  debug ACL:  * a@QPID a@qpid b2@QPID b3@QPID b@QPID b@qpid
  debug ACL: Rule list: 10 ACL rules found:
  debug ACL:    1 allow [*] delete broker
  warning ACL rule ignored: Broker never checks for rules with
                            action: 'delete' and object: 'broker'
  debug ACL:    2 allow [*] create queue name=abc
  debug ACL:    3 allow [*] create queue exchangename=xyz
  warning ACL rule ignored: Broker checks for rules with
                            action: 'create' and object: 'queue'
                     but will never match with property set: { exchangename=xyz }
  debug ACL:    4 allow [*] create connection host=1.1.1.1
  debug ACL:    5 allow [*] access exchange alternate=abc queuename=xyz
  warning ACL rule ignored: Broker checks for rules with
                            action: 'access' and object: 'exchange'
                     but will never match with property set: { alternate=abc queuename=xyz }
  debug ACL:    6 allow [*] access exchange queuename=xyz
  debug ACL:    7 allow [*] access exchange alternate=abc
  debug ACL:    8 allow [a@qpid] * * exchangename=123
  debug ACL:    9 allow [b@qpid] * *
  debug ACL:   10 allow [*] *
  debug ACL: connections quota: 0 rules found:
  debug ACL: queues quota: 0 rules found:
  debug ACL: Load Rules
  debug ACL: Processing 10 allow [*] *
  debug ACL: FoundMode allow
  debug ACL: Processing  9 allow [b@qpid] * *
  debug ACL: Adding actions {access,bind,consume,create,delete,move,publish,purge,
                             redirect,reroute,unbind,update}
                 to objects {broker,connection,exchange,link,method,query,queue}
                 with props { }
                  for users {b@qpid}
  debug ACL: Processing  8 allow [a@qpid] * * exchangename=123
  debug ACL: Adding actions {access,bind,consume,create,delete,move,publish,purge,
                             redirect,reroute,unbind,update}
                 to objects {broker,connection,exchange,link,method,query,queue}
                 with props { exchangename=123 }
                  for users {a@qpid}
  debug ACL: Processing  7 allow [*] access exchange alternate=abc
  debug ACL: Adding actions {access}
                 to objects {exchange}
                 with props { alternate=abc }
                  for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid}
  debug ACL: Processing  6 allow [*] access exchange queuename=xyz
  debug ACL: Adding actions {access}
                 to objects {exchange}
                 with props { queuename=xyz }
                  for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid}
  debug ACL: Processing  5 allow [*] access exchange alternate=abc queuename=xyz
  debug ACL: Processing  4 allow [*] create connection host=1.1.1.1
  debug ACL: Processing  3 allow [*] create queue exchangename=xyz
  debug ACL: Processing  2 allow [*] create queue name=abc
  debug ACL: Adding actions {create}
                 to objects {queue}
                 with props { name=abc }
                  for users {*,a@QPID,a@qpid,b2@QPID,b3@QPID,b@QPID,b@qpid}
  debug ACL: Processing  1 allow [*] delete broker
  debug ACL: global Connection Rule list : 1 rules found :
  debug ACL:    1 [ruleMode = allow {(1.1.1.1,1.1.1.1)}
  debug ACL: User Connection Rule lists : 0 user lists found :
  debug ACL: Transfer ACL is Enabled!
  info ACL Plugin loaded
</programlisting>
                  <para>
                    The previous illustration is interesting because it shows the settings as the <emphasis>all</emphasis> keywords are
                    being expanded. However, that does not show the information about what is actually going into the ACL lookup tables.
                  </para>
                  <para>
                    The next two illustrations show additional information provided by Trace-level logs for ACL startup.
                    The first shows a dump of the broker's internal
                    action/object/properties table. This table is authoratative.
                  </para>
<programlisting>
  trace ACL: Definitions of action, object, (allowed properties) lookups
  trace ACL: Lookup  1: "User querying message timestamp setting  "
                          access   broker     ()
  trace ACL: Lookup  2: "AMQP 0-10 protocol received 'query'      "
                          access   exchange   (name)
  trace ACL: Lookup  3: "AMQP 0-10 query binding                  "
                          access   exchange   (name,routingkey,queuename)
  trace ACL: Lookup  4: "AMQP 0-10 exchange declare               "
                          access   exchange   (name,durable,autodelete,type,alternate)
  trace ACL: Lookup  5: "AMQP 1.0 exchange access                 "
                          access   exchange   (name,durable,type)
  trace ACL: Lookup  6: "AMQP 1.0 node resolution                 "
                          access   exchange   (name)
  trace ACL: Lookup  7: "Management method request                "
                          access   method     (name,schemapackage,schemaclass)
  trace ACL: Lookup  8: "Management agent method request          "
                          access   method     (name,schemapackage,schemaclass)
  trace ACL: Lookup  9: "Management agent query                   "
                          access   query      (name,schemaclass)
  trace ACL: Lookup 10: "QMF 'query queue' method                 "
                          access   queue      (name)
  trace ACL: Lookup 11: "AMQP 0-10 query                          "
                          access   queue      (name)
  trace ACL: Lookup 12: "AMQP 0-10 queue declare                  "
                          access   queue      (name,durable,autodelete,exclusive,alternate,
                            policytype,queuemaxsizelowerlimit,queuemaxsizeupperlimit,
                            queuemaxcountlowerlimit,queuemaxcountupperlimit)
  trace ACL: Lookup 13: "AMQP 1.0 queue access                    "
                          access   queue      (name,durable,autodelete,exclusive,alternate,
                            policytype,queuemaxsizelowerlimit,queuemaxsizeupperlimit,
                            queuemaxcountlowerlimit,queuemaxcountupperlimit)
  trace ACL: Lookup 14: "AMQP 1.0 node resolution                 "
                          access   queue      (name)
  trace ACL: Lookup 15: "AMQP 0-10 or QMF bind request            "
                          bind     exchange   (name,routingkey,queuename)
  trace ACL: Lookup 16: "AMQP 1.0 new outgoing link from exchange "
                          bind     exchange   (name,routingkey,queuename)
  trace ACL: Lookup 17: "AMQP 0-10 subscribe request              "
                          consume  queue      (name)
  trace ACL: Lookup 18: "AMQP 1.0 new outgoing link from queue    "
                          consume  queue      (name)
  trace ACL: Lookup 19: "TCP/IP connection creation               "
                          create   connection (host)
  trace ACL: Lookup 20: "Create exchange                          "
                          create   exchange   (name,durable,autodelete,type,alternate)
  trace ACL: Lookup 21: "Interbroker link creation                "
                          create   link       ()
  trace ACL: Lookup 22: "Interbroker link creation                "
                          create   link       ()
  trace ACL: Lookup 23: "Create queue                             "
                          create   queue      (name,durable,autodelete,exclusive,
                            alternate,policytype,paging,
                            queuemaxsizelowerlimit,queuemaxsizeupperlimit,
                            queuemaxcountlowerlimit,queuemaxcountupperlimit,
                            filemaxsizelowerlimit,filemaxsizeupperlimit,
                            filemaxcountlowerlimit,filemaxcountupperlimit,
                            pageslowerlimit,pagesupperlimit,
                            pagefactorlowerlimit,pagefactorupperlimit)
  trace ACL: Lookup 24: "Delete exchange                          "
                          delete   exchange   (name,durable,type,alternate)
  trace ACL: Lookup 25: "Delete queue                             "
                          delete   queue      (name,durable,autodelete,exclusive,
                            alternate,policytype)
  trace ACL: Lookup 26: "Management 'move queue' request          "
                          move     queue      (name,queuename)
  trace ACL: Lookup 27: "AMQP 0-10 received message processing    "
                          publish  exchange   (name,routingkey)
  trace ACL: Lookup 28: "AMQP 1.0 establish sender link to queue  "
                          publish  exchange   (routingkey)
  trace ACL: Lookup 29: "AMQP 1.0 received message processing     "
                          publish  exchange   (name,routingkey)
  trace ACL: Lookup 30: "Management 'purge queue' request         "
                          purge    queue      (name)
  trace ACL: Lookup 31: "Management 'purge queue' request         "
                          purge    queue      (name)
  trace ACL: Lookup 32: "Management 'redirect queue' request      "
                          redirect queue      (name,queuename)
  trace ACL: Lookup 33: "Management 'reroute queue' request       "
                          reroute  queue      (name,exchangename)
  trace ACL: Lookup 34: "Management 'unbind exchange' request     "
                          unbind   exchange   (name,routingkey,queuename)
  trace ACL: Lookup 35: "User modifying message timestamp setting "
                          update   broker     ()
</programlisting>
                  <para>
                    The final illustration shows a dump of every rule for every user in the ACL database.
                    It includes the user name, action, object, original ACL rule number, allow or deny status,
                    and a cross reference indicating which Lookup Events the rule could possibly satisfy.
                  </para>
                  <para>
                    Note that rules identified by <emphasis>User: *</emphasis> are the rules in effect
                    for users otherwise unnamed in the ACL file.
                  </para>

<programlisting>
  trace ACL: Decision rule cross reference
  trace ACL: User: b@qpid   access   broker
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (1)
  trace ACL: User: *        access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: *        access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: a@QPID   access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: a@QPID   access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: a@qpid   access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: a@qpid   access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: b2@QPID  access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: b2@QPID  access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: b3@QPID  access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: b3@QPID  access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: b@QPID   access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: b@QPID   access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: b@qpid   access   exchange
                        Rule: [rule 6 ruleMode = allow props{ queuename=xyz }]
                              may match Lookups : (3)
  trace ACL: User: b@qpid   access   exchange
                        Rule: [rule 7 ruleMode = allow props{ alternate=abc }]
                              may match Lookups : (4)
  trace ACL: User: b@qpid   access   exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (2,3,4,5,6)
  trace ACL: User: b@qpid   access   method
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (7,8)
  trace ACL: User: b@qpid   access   query
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (9)
  trace ACL: User: b@qpid   access   queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (10,11,12,13,14)
  trace ACL: User: b@qpid   bind     exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (15,16)
  trace ACL: User: b@qpid   consume  queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (17,18)
  trace ACL: User: b@qpid   create   connection
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (19)
  trace ACL: User: b@qpid   create   exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (20)
  trace ACL: User: b@qpid   create   link
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (21,22)
  trace ACL: User: *        create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: a@QPID   create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: a@qpid   create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: b2@QPID  create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: b3@QPID  create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: b@QPID   create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: b@qpid   create   queue
                        Rule: [rule 2 ruleMode = allow props{ name=abc }]
                              may match Lookups : (23)
  trace ACL: User: b@qpid   create   queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (23)
  trace ACL: User: b@qpid   delete   exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (24)
  trace ACL: User: b@qpid   delete   queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (25)
  trace ACL: User: b@qpid   move     queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (26)
  trace ACL: User: b@qpid   publish  exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (27,28,29)
  trace ACL: User: b@qpid   purge    queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (30,31)
  trace ACL: User: b@qpid   redirect queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (32)
  trace ACL: User: a@qpid   reroute  queue
                        Rule: [rule 8 ruleMode = allow props{ exchangename=123 }]
                              may match Lookups : (33)
  trace ACL: User: b@qpid   reroute  queue
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (33)
  trace ACL: User: b@qpid   unbind   exchange
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (34)
  trace ACL: User: b@qpid   update   broker
                        Rule: [rule 9 ruleMode = allow props{ }]
                              may match Lookups : (35)
</programlisting>

                </section>
              </section>

              <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Quotas">
                <title>User Connection and Queue Quotas</title>
                <para>
                  The ACL module enforces various quotas and thereby limits user activity.
                </para>

                <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Connection_Limits">
                  <title>Connection Count Limits</title>
                  <para>
                    The ACL module creates broker command line switches that set limits on the number of concurrent connections allowed per user or per client host address. These settings are not specified in the ACL file.
                  </para>
                  <para>
                    <programlisting>
    --max-connections           N
    --connection-limit-per-user N
    --connection-limit-per-ip   N
                    </programlisting>
                  </para>
                  <para>
                    <command>--max-connections</command> specifies an upper limit for all user connections.
                  </para>
                  <para>
                    <command>--connection-limit-per-user</command> specifies an upper limit for each user based on the authenticated user name. This limit is enforced regardless of the client IP address from which the connection originates.
                  </para>
                  <para>
                    <command>--connection-limit-per-ip</command> specifies an upper limit for connections for all users based on the originating client IP address. This limit is enforced regardless of the user credentials presented with the connection.
                    <itemizedlist>
                      <listitem>
                        Note that addresses using different transports are counted separately even though the originating host is actually the same physical machine. In the setting illustrated above a host would allow N_IP connections from [::1] IPv6 transport localhost and another N_IP connections from [127.0.0.1] IPv4 transport localhost.
                      </listitem>
                      <listitem>
                        The connection-limit-per-ip and connection-limit-per-user counts are active simultaneously. From a given client system users may be denied access to the broker by either connection limit.
                      </listitem>
                    </itemizedlist>
                  </para>
                  <para>
                    The 0.22 C++ Broker ACL module accepts fine grained per-user connection limits through quota rules in the ACL file.
                  </para>
                  <para>
                    <programlisting>
    quota connections 10 admins userX@QPID
                    </programlisting>
                  </para>
                  <para>
                    <itemizedlist>
                      <listitem>
                        User <literal>all</literal> receives the value passed by the command line switch <literal>--connection-limit-per-user</literal>.
                      </listitem>
                      <listitem>
                        Values specified in the ACL rule for user <literal>all</literal> overwrite the value specified on the command line if any.
                      </listitem>
                      <listitem>
                        Connection quotas values are determined by first searching for the authenticated user name. If that user name is not specified then the value for user <literal>all</literal>
                        is used. If user <literal>all</literal> is not specified then the connection is denied.
                      </listitem>
                      <listitem>
                        The connection quota values range from 0..65530 inclusive. A value of zero disables connections from that user.
                      </listitem>
                      <listitem>
                        A user's quota may be specified many times in the ACL rule file. Only the last value specified is retained and enforced.
                      </listitem>
                      <listitem>
                        Per-user connection quotas are disabled when two conditions are true: 1) No --connection-limit-per-user command line switch and 2) No <literal>quota connections</literal>
                        rules in the ACL file. Per-user connections are always counted even if connection quotas are not enforced. This supports ACL file reloading that may subsequently
                        enable per-user connection quotas.
                      </listitem>
                      <listitem>
                        An ACL file reload may lower a user's connection quota value to a number lower than the user's current connection count. In that case the active connections
                        remain unaffected. New connections are denied until that user closes enough of his connections so that his count falls below the configured limit.
                      </listitem>
                    </itemizedlist>
                  </para>
                </section>

                <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Connection_Host_Limits">
                  <title>Connection Limits by Host Name</title>
                  <para>
                    The 0.30 C++ Broker ACL module adds the ability to create allow and deny lists of the TCP/IP hosts from which users may connect. The rule accepts these forms:
                  </para>
                  <para>
                    <programlisting>
    acl allow user create connection host=host1
    acl allow user create connection host=host1,host2
    acl deny  user create connection host=all
                    </programlisting>
                  </para>
                  <para>
                    Using the form <command>host=host1</command> specifies a single host. With a single host the name may resolve to multiple TCP/IP addresses. For example <emphasis>localhost</emphasis> resolves to both <emphasis>127.0.0.1</emphasis> and <emphasis>::1</emphasis> and possibly many other addresses. A connection from any of the addresses associated with this host matches the rule and the connection is allowed or denied accordingly.
                  </para>
                  <para>
                    Using the form <command>host=host1,host2</command> specifies a range of TCP/IP addresses. With a host range each host must resolve to a single TCP/IP address and the second address must be numerically larger than the first. A connection from any host where host &#62;= host1 and host &#60;= host2 match the rule and the connection is allowed or denied accordingly.
                  </para>
                  <para>
                    Using the form <command>host=all</command> specifies all TCP/IP addresses. A connection from any host matches the rule and the connection is allowed or denied accordingly.
                  </para>
                  <para>
                    Connection denial is only applied to incoming TCP/IP connections. Other socket types are not subjected to nor denied by range checks.
                  </para>
                  <para>
                    Connection creation rules are divided into three categories:
                  </para>
                  <procedure>
                    <step>
                      <para>
                        User = all, host != all
                      </para>
                      <para>
                        These define global rules and are applied before any specific user rules. 
                        These rules may be used to reject connections before any AMPQ protocol is run and before
                        any user names have been negotiated.
                      </para>
                    </step>
                    <step>
                      <para>
                        User != all, host = any legal host or 'all'
                      </para>
                      <para>
                        These define user rules. These rules are applied after the global rules and
                        after the AMQP protocol has negotiated user identities.
                      </para>
                    </step>
                    <step>
                      <para>
                        User = all, host = all
                      </para>
                      <para>
                        This rule defines what to do if no other rule matches. The default value is "ALLOW".
                        Only one rule of this type may be defined.
                      </para>
                    </step>
                  </procedure>

                  <para>
                    The following example illustrates how this feature can be used.
                  </para>
                  <para>
                    <programlisting>
    group admins alice bob chuck
    group Company1 c1_usera c1_userb
    group Company2 c2_userx c2_usery c2_userz
    acl allow admins   create connection host=localhost
    acl allow admins   create connection host=10.0.0.0,10.255.255.255
    acl allow admins   create connection host=192.168.0.0,192.168.255.255
    acl allow admins   create connection host=[fc00::],[fc00::ff]
    acl allow Company1 create connection host=company1.com
    acl deny  Company1 create connection host=all
    acl allow Company2 create connection host=company2.com
    acl deny  Company2 create connection host=all
                    </programlisting>
                  </para>
                  <para>
                    In this example admins may connect from localhost or from any system on the 10.0.0.0/24, 192.168.0.0/16, and fc00::/7 subnets. Company1 users may connect only from company1.com and Company2 users may connect only from company2.com.
                    However, this example has a flaw. Although the admins group has specific hosts
                    from which it is allowed to make connections it is not blocked from connecting
                    from anywhere. The Company1 and Company2 groups are blocked appropriately.
                    This ACL file may be rewritten as follows:
                  </para>
                  <para>
                    <programlisting>
    group admins alice bob chuck
    group Company1 c1_usera c1_userb
    group Company2 c2_userx c2_usery c2_userz
    acl allow admins   create connection host=localhost
    acl allow admins   create connection host=10.0.0.0,10.255.255.255
    acl allow admins   create connection host=192.168.0.0,192.168.255.255
    acl allow admins   create connection host=[fc00::],[fc00::ff]
    acl allow Company1 create connection host=company1.com
    acl allow Company2 create connection host=company2.com
    acl deny  all      create connection host=all
                    </programlisting>
                  </para>
                  <para>
                    Now admins are blocked from connecting from anywhere but their allowed
                    hosts.
                  </para>

                </section>

                <section id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Queue_Limits">
                  <title>Queue Limits</title>
                  <para>
                    The ACL module creates a broker command line switch that set limits on the number of queues each user is allowed to create. This settings is not specified in the ACL file.
                  </para>
                  <para>
                    <programlisting>
    --max-queues-per-user N
                    </programlisting>
                  </para>
                  <para>
                    The queue limit is set for all users on the broker.
                  </para>
                  <para>
                    The 0.22 C++ Broker ACL module accepts fine grained per-user queue limits through quota rules in the ACL file.
                  </para>
                  <para>
                    <programlisting>
    quota queues 10 admins userX@QPID
                    </programlisting>
                  </para>
                  <para>
                    <itemizedlist>
                      <listitem>
                        User <literal>all</literal> receives the value passed by the command line switch <literal>--max-queues-per-user</literal>.
                      </listitem>
                      <listitem>
                        Values specified in the ACL rule for user <literal>all</literal> overwrite the value specified on the command line if any.
                      </listitem>
                      <listitem>
                        Queue quotas values are determined by first searching for the authenticated user name. If that user name is not specified then the value for user <literal>all</literal>
                        is used. If user <literal>all</literal> is not specified then the queue creation is denied.
                      </listitem>
                      <listitem>
                        The queue quota values range from 0..65530 inclusive. A value of zero disables queue creation by that user.
                      </listitem>
                      <listitem>
                        A user's quota may be specified many times in the ACL rule file. Only the last value specified is retained and enforced.
                      </listitem>
                      <listitem>
                        Per-user queue quotas are disabled when two conditions are true: 1) No --queue-limit-per-user command line switch and 2) No <literal>quota queues</literal>
                        rules in the ACL file. Per-user queue creations are always counted even if queue quotas are not enforced. This supports ACL file reloading that may subsequently
                        enable per-user queue quotas.
                      </listitem>
                      <listitem>
                        An ACL file reload may lower a user's queue quota value to a number lower than the user's current queue count. In that case the active queues
                        remain unaffected. New queues are denied until that user closes enough of his queues so that his count falls below the configured limit.
                      </listitem>
                    </itemizedlist>
                  </para>
                </section>

	      </section>

	 <!--          ###########################          --> <section id="sect-Messaging_User_Guide-Security-Encryption_using_SSL">
		<title>Encryption using SSL</title>
		 <para>
			Encryption and certificate management for <command>qpidd</command> is provided by Mozilla&#39;s Network Security Services Library (NSS).
		</para>
		 <orderedlist id="orde-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_for_the_RHM_broker">
			<title>Enabling SSL for the Qpid broker</title>
			 <listitem>
				<para>
					You will need a certificate that has been signed by a Certification Authority (CA). This certificate will also need to be trusted by your client. If you require client authentication in addition to server authentication, the client&#39;s certificate will also need to be signed by a CA and trusted by the broker.
				</para>
				 <para>
					In the broker, SSL is provided through the <command>ssl.so</command> module. This module is installed and loaded by default in Qpid. To enable the module, you need to specify the location of the database containing the certificate and key to use. This is done using the <command>ssl-cert-db</command> option.
				</para>
				 <para>
					The certificate database is created and managed by the Mozilla Network Security Services (NSS) <command>certutil</command> tool. Information on this utility can be found on the <ulink url="http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html">Mozilla website</ulink>, including tutorials on setting up and testing SSL connections. The certificate database will generally be password protected. The safest way to specify the password is to place it in a protected file, use the password file when creating the database, and specify the password file with the <command>ssl-cert-password-file</command> option when starting the broker.
				</para>
				 <para>
					The following script shows how to create a certificate database using certutil:
				</para>
				 <!--   TODO: improve description   -->
<programlisting>
mkdir ${CERT_DIR}
certutil -N -d ${CERT_DIR} -f ${CERT_PW_FILE}
certutil -S -d ${CERT_DIR} -n ${NICKNAME} -s &#34;CN=${NICKNAME}&#34; -t &#34;CT,,&#34; -x -f ${CERT_PW_FILE} -z /usr/bin/certutil
</programlisting>
				 <para>
					When starting the broker, set <command>ssl-cert-password-file</command> to the value of <command>${CERT_PW_FILE}</command>, set <command>ssl-cert-db</command> to the value of <command>${CERT_DIR}</command>, and set <command>ssl-cert-name</command> to the value of <command>${NICKNAME}</command>.
				</para>

			</listitem>
			 <!--          SSL options          --> <listitem>
				<para>
					The following SSL options can be used when starting the broker:
					<variablelist>
						<varlistentry>
							<term><command>--ssl-use-export-policy</command></term>
							 <listitem>
								<para>
									Use NSS export policy
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-cert-password-file <replaceable>PATH</replaceable></command></term>
							 <listitem>
								<para>
									Required. Plain-text file containing password to use for accessing certificate database.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-cert-db <replaceable>PATH</replaceable></command></term>
							 <listitem>
								<para>
									Required. Path to directory containing certificate database.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-cert-name <replaceable>NAME</replaceable></command></term>
							 <listitem>
								<para>
									Name of the certificate to use. Default is <literal>localhost.localdomain</literal>.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-port <replaceable>NUMBER</replaceable></command></term>
							 <listitem>
								<para>
									Port on which to listen for SSL connections. If no port is specified, port 5671 is used.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-require-client-authentication</command></term>
							 <listitem>
								<para>
									Require SSL client authentication (i.e. verification of a client certificate) during the SSL handshake. This occurs before SASL authentication, and is independent of SASL.
								</para>
								 <para>
									This option enables the <literal>EXTERNAL</literal> SASL mechanism for SSL connections. If the client chooses the <literal>EXTERNAL</literal> mechanism, the client&#39;s identity is taken from the validated SSL certificate, using the <literal>CN</literal>literal&#62;, and appending any <literal>DC</literal>literal&#62;s to create the domain. For instance, if the certificate contains the properties <literal>CN=bob</literal>, <literal>DC=acme</literal>, <literal>DC=com</literal>, the client&#39;s identity is <literal>bob@acme.com</literal>.
								</para>
								 <para>
									If the client chooses a different SASL mechanism, the identity take from the client certificate will be replaced by that negotiated during the SASL handshake.
								</para>

							</listitem>

						</varlistentry>
						 <varlistentry>
							<term><command>--ssl-sasl-no-dict</command></term>
							 <listitem>
								<para>
									Do not accept SASL mechanisms that can be compromised by dictionary attacks. This prevents a weaker mechanism being selected instead of <literal>EXTERNAL</literal>, which is not vulnerable to dictionary attacks.
								</para>

							</listitem>

						</varlistentry>

					</variablelist>
					 Also relevant is the <command>--require-encryption</command> broker option. This will cause <command>qpidd</command> to only accept encrypted connections.
				</para>

			</listitem>

		</orderedlist>
		 <!--                 --> <variablelist id="vari-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_in_Clients">
			<title>Enabling SSL in Clients</title>
			 <varlistentry>
				<term>C++ clients:</term>
				 <listitem>
					<para>
						<orderedlist>
							<listitem>
								<para>
									In C++ clients, SSL is implemented in the <command>sslconnector.so</command> module. This module is installed and loaded by default in Qpid.
								</para>
								 <para>
									The following options can be specified for C++ clients using environment variables:
								</para>
								 <table frame="all" id="tabl-Messaging_User_Guide-Enabling_SSL_in_Clients-SSL_Client_Environment_Variables_for_C_clients">
									<title>SSL Client Environment Variables for C++ clients</title>
									 <tgroup align="left" cols="2" colsep="1" rowsep="1">
										<colspec colname="c1"></colspec>
										 <colspec colname="c2"></colspec>
										 <thead>
											<row>
												<entry align="center" nameend="c2" namest="c1">
													SSL Client Options for C++ clients
												</entry>

											</row>

										</thead>
										 <tbody>
											<row>
												<entry>
													<command>QPID_SSL_USE_EXPORT_POLICY</command>
												</entry>
												 <entry>
													Use NSS export policy
												</entry>

											</row>
											 <row>
												<entry>
													<command>QPID_SSL_CERT_PASSWORD_FILE <replaceable>PATH</replaceable></command>
												</entry>
												 <entry>
													File containing password to use for accessing certificate database
												</entry>

											</row>
											 <row>
												<entry>
													<command>QPID_SSL_CERT_DB <replaceable>PATH</replaceable></command>
												</entry>
												 <entry>
													Path to directory containing certificate database
												</entry>

											</row>
											 <row>
												<entry>
													<command>QPID_SSL_CERT_NAME <replaceable>NAME</replaceable></command>
												</entry>
												 <entry>
													Name of the certificate to use. When SSL client authentication is enabled, a certificate name should normally be provided.
												</entry>

											</row>

										</tbody>

									</tgroup>

								</table>
								 <!--         ########         -->
							</listitem>
							 <listitem>
								<para>
									When using SSL connections, clients must specify the location of the certificate database, a directory that contains the client&#39;s certificate and the public key of the Certificate Authority. This can be done by setting the environment variable <command>QPID_SSL_CERT_DB</command> to the full pathname of the directory. If a connection uses SSL client authentication, the client&#39;s password is also needed&mdash;the password should be placed in a protected file, and the <command>QPID_SSL_CERT_PASSWORD_FILE</command> variable should be set to the location of the file containing this password.
								</para>

							</listitem>
							 <listitem>
								<para>
									To open an SSL enabled connection in the Qpid Messaging API, set the <parameter>protocol</parameter> connection option to <parameter>ssl</parameter>.
								</para>

							</listitem>

						</orderedlist>

					</para>

				</listitem>

			</varlistentry>
			 <varlistentry>
				<term>Java clients:</term>
				 <listitem>
					<para>
						<orderedlist>
							<listitem>
								<para>
									For both server and client authentication, import the trusted CA to your trust store and keystore and generate keys for them. Create a certificate request using the generated keys and then create a certificate using the request. You can then import the signed certificate into your keystore. Pass the following arguments to the Java JVM when starting your client:
<programlisting>
-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks
-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
-Djavax.net.ssl.trustStorePassword=password
</programlisting>

								</para>

							</listitem>
							 <listitem>
								<para>
									For server side authentication only, import the trusted CA to your trust store and pass the following arguments to the Java JVM when starting your client:
<programlisting>
-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
-Djavax.net.ssl.trustStorePassword=password
</programlisting>

								</para>

							</listitem>
							 <listitem>
								<para>
									Java clients must use the SSL option in the connection URL to enable SSL encryption, e.g.
								</para>

<programlisting>amqp://username:password@clientid/test?brokerlist=&#39;tcp://localhost:5672?ssl=&#39;true&#39;&#39;
</programlisting>

							</listitem>
							 <listitem>
								<para>
									If you need to debug problems in an SSL connection, enable Java&#39;s SSL debugging by passing the argument <literal>-Djavax.net.debug=ssl</literal> to the Java JVM when starting your client.
								</para>

							</listitem>

						</orderedlist>

					</para>

				</listitem>

			</varlistentry>

		</variablelist>

	</section>


</section>