http://git-wip-us.apache.org/repos/asf/qpid-site/blob/1a8679bf/content/releases/qpid-cpp-trunk/cpp-broker/book/chap-Messaging_User_Guide-Security.html ---------------------------------------------------------------------- diff --git a/content/releases/qpid-cpp-trunk/cpp-broker/book/chap-Messaging_User_Guide-Security.html b/content/releases/qpid-cpp-trunk/cpp-broker/book/chap-Messaging_User_Guide-Security.html deleted file mode 100644 index 76ec8f0..0000000 --- a/content/releases/qpid-cpp-trunk/cpp-broker/book/chap-Messaging_User_Guide-Security.html +++ /dev/null @@ -1,1374 +0,0 @@ -<!DOCTYPE html> -<!-- - - - - 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. - - ---> -<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en"> - <head> - <title>1.5. Security - Apache Qpid™</title> - <meta http-equiv="X-UA-Compatible" content="IE=edge"/> - <meta name="viewport" content="width=device-width, initial-scale=1.0"/> - <link rel="stylesheet" href="/site.css" type="text/css" async="async"/> - <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/> - <script type="text/javascript">var _deferredFunctions = [];</script> - <script type="text/javascript" src="/deferred.js" defer="defer"></script> - <!--[if lte IE 8]> - <link rel="stylesheet" href="/ie.css" type="text/css"/> - <script type="text/javascript" src="/html5shiv.js"></script> - <![endif]--> - - <!-- Redirects for `go get` and godoc.org --> - <meta name="go-import" - content="qpid.apache.org git https://git-wip-us.apache.org/repos/asf/qpid-proton.git"/> - <meta name="go-source" - content="qpid.apache.org -https://github.com/apache/qpid-proton/blob/go1/README.md -https://github.com/apache/qpid-proton/tree/go1{/dir} -https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/> - </head> - <body> - <div id="-content"> - <div id="-top" class="panel"> - <a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a> - - <a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a> - - <ul id="-global-navigation"> - <li><a id="-logotype" href="/index.html">Apache Qpid<sup>™</sup></a></li> - <li><a href="/documentation.html">Documentation</a></li> - <li><a href="/download.html">Download</a></li> - <li><a href="/discussion.html">Discussion</a></li> - </ul> - </div> - - <div id="-menu" class="panel" style="display: none;"> - <div class="flex"> - <section> - <h3>Project</h3> - - <ul> - <li><a href="/overview.html">Overview</a></li> - <li><a href="/components/index.html">Components</a></li> - <li><a href="/releases/index.html">Releases</a></li> - </ul> - </section> - - <section> - <h3>Messaging APIs</h3> - - <ul> - <li><a href="/proton/index.html">Qpid Proton</a></li> - <li><a href="/components/jms/index.html">Qpid JMS</a></li> - <li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li> - </ul> - </section> - - <section> - <h3>Servers and tools</h3> - - <ul> - <li><a href="/components/java-broker/index.html">Broker for Java</a></li> - <li><a href="/components/cpp-broker/index.html">C++ broker</a></li> - <li><a href="/components/dispatch-router/index.html">Dispatch router</a></li> - </ul> - </section> - - <section> - <h3>Resources</h3> - - <ul> - <li><a href="/dashboard.html">Dashboard</a></li> - <li><a href="https://cwiki.apache.org/confluence/display/qpid/Index";>Wiki</a></li> - <li><a href="/resources.html">More resources</a></li> - </ul> - </section> - </div> - </div> - - <div id="-search" class="panel" style="display: none;"> - <form action="http://www.google.com/search"; method="get"> - <input type="hidden" name="sitesearch" value="qpid.apache.org"/> - <input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/> - <button type="submit">Search</button> - <a href="/search.html">More ways to search</a> - </form> - </div> - - <div id="-middle" class="panel"> - <ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/releases/index.html">Releases</a></li><li><a href="/releases/qpid-cpp-trunk/index.html">Qpid C++ Trunk</a></li><li><a href="/releases/qpid-cpp-trunk/cpp-broker/book/index.html">AMQP Messaging Broker (Implemented in C++)</a></li><li>1.5. Security</li></ul> - - <div id="-middle-content"> - <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.5. Security</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="chap-Messaging_User_Guide-Broker_Federation.html">Prev</a> </td><th align="center" width="60%">Chapter 1.  - Running the AMQP Messaging Broker - </th><td align="right" width="20%"> <a accesskey="n" href="ch01s06.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="chap-Messaging_User_Guide-Security"></a>1.5. Security</h2></div></div></div><p> - 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). - </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-Messaging_User_Guide-Security-User_Authentication"></a>1.5.1. User Authentication</h3></div></div></div><p> - 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 <span class="command"><strong>CRAM-MD5</strong></span>, <span class="command"><strong>DIGEST-MD5</strong></span>, or <span class="command"><strong>GSSAPI</strong></span>. The <span class="command"><strong>ANONYMOUS</strong></span> method is not secure. The <span class="command"><strong>PLAIN</strong></span> method is secure only when used together with SSL. - </p><p> - Both the Qpid broker and Qpid clients use the <a class="ulink" href="http://cyrusimap.web.cmu.edu/"; target="_top">Cyrus SASL library</a>, 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 <span class="command"><strong>SASL PLAIN</strong></span>. If you are not using SSL, you should configure SASL to use <span class="command"><strong>CRAM-MD5</strong></span>, <span class="command"><strong>DIGEST-MD5</strong></span>, or <span class="command"><strong>GSSAPI</strong></span> (which provides Kerberos authentication). For information on configuring these and other options in SASL, see the Cyrus SASL documentation. - </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p> - The <span class="command"><strong>SASL PLAIN</strong></span> method sends passwords in cleartext, and is vulnerable to man-in-the-middle attacks unless SSL (Secure Socket Layer) is also used (see <a class="xref" href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Security-Encryption_using_SSL" title="1.5.4. Encryption using SSL">Section 1.5.4, “Encryption using SSL”</a>). - </p><p> - If you are not using SSL, we recommend that you disable <span class="command"><strong>PLAIN</strong></span> authentication in the broker. - </p></div><p> - The Qpid broker uses the <span class="command"><strong>auth yes|no</strong></span> option to determine whether to use SASL authentication. Turn on authentication by setting <span class="command"><strong>auth</strong></span> to <span class="command"><strong>yes</strong></span> in <code class="filename">/etc/qpidd.conf</code>: - </p><pre class="programlisting"> -# /etc/qpidd.conf -# -# Set auth to 'yes' or 'no' - -auth=yes -</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-User_Authentication-Configuring_SASL"></a>1.5.1.1. Configuring SASL</h4></div></div></div><p> - On Linux systems, the SASL configuration file is generally found in <code class="filename">/etc/sasl2/qpidd.conf</code> or <code class="filename">/usr/lib/sasl2/qpidd.conf</code>. - </p><p> - The SASL database contains user names and passwords for SASL. In SASL, a user may be associated with a <em class="firstterm">realm</em>. The Qpid broker authenticates users in the <span class="command"><strong>QPID</strong></span> realm by default, but it can be set to a different realm using the <span class="command"><strong>realm</strong></span> option: - </p><pre class="programlisting"> -# /etc/qpidd.conf -# -# Set the SASL realm using 'realm=' - -auth=yes -realm=QPID -</pre><p> - The SASL database is installed at <code class="filename">/var/lib/qpidd/qpidd.sasldb</code>; initially, it has one user named <span class="command"><strong>guest</strong></span> in the <span class="command"><strong>QPID</strong></span> realm, and the password for this user is <span class="command"><strong>guest</strong></span>. - </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> - The user database is readable only by the <code class="systemitem">qpidd</code> user. When run as a daemon, Qpid always runs as the <code class="systemitem">qpidd</code> user. If you start the broker from a user other than the <code class="systemitem">qpidd</code> user, you will need to either reconfigure SASL or turn authentication off. - </p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p> - 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 <code class="systemitem">qpidd</code> user is the only user that can read the database. If you modify permissions, be careful not to expose the SASL database. - </p></div><p> - Add new users to the database by using the <span class="command"><strong>saslpasswd2</strong></span> command, which specifies a realm and a user ID. A user ID takes the form <span class="command"><strong><em class="replaceable"><code>user-id</code></em>@<em class="replaceable"><code>domain</code></em>.</strong></span>. - </p><pre class="screen"># saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <em class="replaceable"><code>realm</code></em> <em class="replaceable"><code>new_user_name</code></em></pre><p> - To list the users in the SASL database, use <span class="command"><strong>sasldblistusers2</strong></span>: - </p><pre class="screen"># sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb -</pre><p> - If you are using <span class="command"><strong>PLAIN</strong></span> 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. - </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-User_Authentication-Kerberos"></a>1.5.1.2. Kerberos</h4></div></div></div><p> - Both the Qpid broker and Qpid users are 'principals' of the Kerberos server, which means that they are both clients of the Kerberos authentication services. - </p><p> - To use Kerberos, both the Qpid broker and each Qpid user must be authenticated on the Kerberos server: - </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p> - Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client: - </p><pre class="screen">$ sudo yum install cyrus-sasl-gssapi krb5-workstation</pre></li><li class="step"><p> - Make sure that the Qpid broker is registered in the Kerberos database. - </p><p> - Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format <code class="literal">primary/instance@REALM</code>. For a Qpid broker, the primary is <code class="literal">qpidd</code>, the instance is the fully qualified domain name, which you can obtain using <span class="command"><strong>hostname --fqdn</strong></span>, and the REALM is the Kerberos domain realm. By default, this realm is <code class="literal">QPID</code>, but a different realm can be specified in qpid.conf, e.g.: -</p><pre class="screen">realm=EXAMPLE.COM</pre><p> - - </p><p> - For instance, if the fully qualified domain name is <code class="literal">dublduck.example.com</code> and the Kerberos domain realm is <code class="literal">EXAMPLE.COM</code>, then the principal name is <code class="literal">qpidd/dublduck.example....@example.com</code>. - </p><p> - The following script creates a principal for qpidd: - </p><pre class="programlisting"> -FDQN=`hostname --fqdn` -REALM="EXAMPLE.COM" -kadmin -r $REALM -q "addprinc -randkey -clearpolicy qpidd/$FQDN" -</pre><p> - 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: - </p><pre class="programlisting"> -QPIDD_GROUP="qpidd" -kadmin -r $REALM -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM" -chmod g+r /etc/qpidd.keytab -chgrp $QPIDD_GROUP /etc/qpidd.keytab -</pre><p> - The default location for the keytab file is <code class="filename">/etc/krb5.keytab</code>. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file, e.g.: - </p><pre class="programlisting"> -export KRB5_KTNAME=/etc/qpidd.keytab -</pre><p> - If this is correctly configured, you can now enable kerberos support on the Qpid broker by setting the <code class="varname">auth</code> and <code class="varname">realm</code> options in <code class="filename">/etc/qpidd.conf</code>: - </p><pre class="programlisting"> -# /etc/qpidd.conf -auth=yes -realm=EXAMPLE.COM -</pre><p> - Restart the broker to activate these settings. - </p></li><li class="step"><p> - 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: - </p><pre class="screen">$ kinit u...@realm.com</pre></li></ol></div><p> - Java JMS clients require a few additional steps. - </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p> - The Java JVM must be run with the following arguments: - </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-Djavax.security.auth.useSubjectCredsOnly=false</span></dt><dd><p> - Forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread. - </p></dd><dt><span class="term">-Djava.security.auth.login.config=myjas.conf</span></dt><dd><p> - Specifies the jass configuration file. Here is a sample JASS configuration file: - </p><pre class="programlisting"> -com.sun.security.jgss.initiate { - com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; -}; -</pre></dd><dt><span class="term">-Dsun.security.krb5.debug=true</span></dt><dd><p> - Enables detailed debug info for troubleshooting - </p></dd></dl></div></li><li class="step"><p> - The client's Connection URL must specify the following Kerberos-specific broker properties: - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - <code class="varname">sasl_mechs</code> must be set to <code class="literal">GSSAPI</code>. - </p></li><li class="listitem"><p> - <code class="varname">sasl_protocol</code> must be set to the principal for the qpidd broker, e.g. <code class="literal">qpidd</code>/ - </p></li><li class="listitem"><p> - <code class="varname">sasl_server</code> must be set to the host for the SASL server, e.g. <code class="literal">sasl.com</code>. - </p></li></ul></div><p> - Here is a sample connection URL for a Kerberos connection: - </p><pre class="screen">amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''</pre></li></ol></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-Messaging_User_Guide-Security-Authorization"></a>1.5.2. Authorization</h3></div></div></div><p> - In Qpid, Authorization specifies which actions can be performed by each authenticated user using an Access Control List (ACL). - </p><p> - Use the <span class="command"><strong>--acl-file</strong></span> command to load the access control list. The filename should have a <code class="filename">.acl</code> extension: - </p><pre class="screen"> - $ qpidd --acl-file <em class="replaceable"><code>./aclfilename.acl</code></em></pre><p> - Each line in an ACL file grants or denies specific rights to a user. If the last line in an ACL file is <code class="literal">acl deny all all</code>, the ACL uses <em class="firstterm">deny mode</em>, and only those rights that are explicitly allowed are granted: - </p><pre class="programlisting"> - acl allow rajith@QPID all all - acl deny all all -</pre><p> - On this server, <code class="literal">rajith@QPID</code> can perform any action, but nobody else can. Deny mode is the default, so the previous example is equivalent to the following ACL file: - </p><pre class="programlisting"> - acl allow rajith@QPID all all -</pre><p> - Alternatively the ACL file may use <em class="firstterm">allow mode</em> by placing: - </p><pre class="programlisting"> - acl allow all all -</pre><p> - as the final line in the ACL file. In <span class="emphasis"><em>allow mode</em></span> all actions by all users are allowed unless otherwise denied by specific ACL rules. - The ACL rule which selects <span class="emphasis"><em>deny mode</em></span> or <span class="emphasis"><em>allow mode</em></span> must be the last line in the ACL rule file. - </p><p> - ACL syntax allows fine-grained access rights for specific actions: - </p><pre class="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 -</pre><p> - An ACL file can define user groups, and assign permissions to them: - </p><pre class="programlisting"> - group admin ted@QPID martin@QPID - acl allow admin create all - acl deny all all -</pre><p> - An ACL file can define per user connection and queue quotas: - </p><pre class="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 -</pre><p> - 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 <span class="command"><strong>publish exchange</strong></span> - query. ACL files with no <span class="emphasis"><em>publish exchange</em></span> rules are noted and the broker short circuits the logic - associated with the per-messsage <span class="emphasis"><em>publish exchange</em></span> ACL query. - However, if an ACL file has any <span class="emphasis"><em>publish exchange</em></span> rules - then the broker is required to perform a <span class="emphasis"><em>publish exchange</em></span> query for each message published. - Users with performance critical applications are encouraged to structure exchanges, queues, and bindings so that - the <span class="emphasis"><em>publish exchange</em></span> ACL rules are unnecessary. - </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntax"></a>1.5.2.1. ACL Syntax</h4></div></div></div><p> - ACL rules follow this syntax: -</p><pre class="programlisting"> -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" -</pre><p> - - ACL rules can also include a single object name (or the keyword <em class="parameter"><code>all</code></em>) and one or more property name value pairs in the form <span class="command"><strong>property=value</strong></span> - </p><p> - The following tables show the possible values for <span class="command"><strong>permission</strong></span>, <span class="command"><strong>action</strong></span>, <span class="command"><strong>object</strong></span>, and <span class="command"><strong>property</strong></span> in an ACL rules file. - </p><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rules_permission"></a><p class="title"><strong>Table 1.12. ACL Rules: permission</strong></p><div class="table-contents"><table border="1" summary="ACL Rules: permission"><colgroup><col /><col /></colgroup><tbody><tr><td> - <span class="command"><strong>allow</strong></span> - </td><td> - <p> - Allow the action - </p> - </td></tr><tr><td> - <span class="command"><strong>allow-log</strong></span> - </td><td> - <p> - Allow the action and log the action in the event log - </p> - </td></tr><tr><td> - <span class="command"><strong>deny</strong></span> - </td><td> - <p> - Deny the action - </p> - </td></tr><tr><td> - <span class="command"><strong>deny-log</strong></span> - </td><td> - <p> - Deny the action and log the action in the event log - </p> - </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesaction"></a><p class="title"><strong>Table 1.13. ACL Rules: action</strong></p><div class="table-contents"><table border="1" summary="ACL Rules: action"><colgroup><col /><col /></colgroup><tbody><tr><td> - <span class="command"><strong>access</strong></span> - </td><td> - <p> - Accessing or reading an object - </p> - </td></tr><tr><td> - <span class="command"><strong>bind</strong></span> - </td><td> - <p> - Associating a queue to an exchange with a routing key. - </p> - </td></tr><tr><td> - <span class="command"><strong>consume</strong></span> - </td><td> - <p> - Using an object - </p> - </td></tr><tr><td> - <span class="command"><strong>create</strong></span> - </td><td> - <p> - Creating an object. - </p> - </td></tr><tr><td> - <span class="command"><strong>delete</strong></span> - </td><td> - <p> - Deleting an object. - </p> - </td></tr><tr><td> - <span class="command"><strong>move</strong></span> - </td><td> - <p> - Moving messages between queues. - </p> - </td></tr><tr><td> - <span class="command"><strong>publish</strong></span> - </td><td> - <p> - Authenticating an incoming message. - </p> - </td></tr><tr><td> - <span class="command"><strong>purge</strong></span> - </td><td> - <p> - Purging a queue. - </p> - </td></tr><tr><td> - <span class="command"><strong>redirect</strong></span> - </td><td> - <p> - Redirecting messages between queues - </p> - </td></tr><tr><td> - <span class="command"><strong>reroute</strong></span> - </td><td> - <p> - Rerouting messages from a queue to an exchange - </p> - </td></tr><tr><td> - <span class="command"><strong>unbind</strong></span> - </td><td> - <p> - Disassociating a queue from an exchange with a routing key. - </p> - </td></tr><tr><td> - <span class="command"><strong>update</strong></span> - </td><td> - <p> - Changing a broker configuration setting. - </p> - </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesobject"></a><p class="title"><strong>Table 1.14. ACL Rules:object</strong></p><div class="table-contents"><table border="1" summary="ACL Rules:object"><colgroup><col /><col /></colgroup><tbody><tr><td> - <span class="command"><strong>broker</strong></span> - </td><td> - <p> - </p> - </td></tr><tr><td> - <span class="command"><strong>connection</strong></span> - </td><td> - <p> - Incoming TCP/IP connection - </p> - </td></tr><tr><td> - <span class="command"><strong>exchange</strong></span> - </td><td> - <p> - </p> - </td></tr><tr><td> - <span class="command"><strong>link</strong></span> - </td><td> - <p> - A federation or inter-broker link - </p> - </td></tr><tr><td> - <span class="command"><strong>method</strong></span> - </td><td> - <p> - Management method - </p> - </td></tr><tr><td> - <span class="command"><strong>query</strong></span> - </td><td> - <p> - Management query of an object or class - </p> - </td></tr><tr><td> - <span class="command"><strong>queue</strong></span> - </td><td> - <p> - </p> - </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesproperty"></a><p class="title"><strong>Table 1.15. ACL Rules: property</strong></p><div class="table-contents"><table border="1" summary="ACL Rules: property"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Property</th><th>Type</th><th>Description</th><th>Usage</th></tr></thead><tbody><tr><td> <span class="command"><strong>name</strong></span> </td><td>String</td><td>Rule refers to objects with this name. When 'name' is blank or absent then the rule - applies to all objects of the given type.</td><td> </td></tr><tr><td> <span class="command"><strong>alternate</strong></span> </td><td>String</td><td>Name of an alternate exchange</td><td>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</td></tr><tr><td> <span class="command"><strong>autodelete</strong></span> </td><td>Boolean</td><td>Indicates whether or not the object gets deleted when the connection that created it is closed</td><td>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE</td></tr><tr><td> <span class="command"><strong>durable</strong></span> </td><td>Boolean</td><td>Rule applies to durable objects</td><td>CREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE, DELETE QUEUE, DELETE EXCHANGE</td></tr><tr><td> <span class="command"><strong>exchangename</strong></span> </td><td>String</td><td>Name of the exchange to which queue's entries are routed</td><td>REROUT E QUEUE</td></tr><tr><td> <span class="command"><strong>filemaxcountlowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for file.max_count (files)</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>filemaxcountupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for file.max_count (files)</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>filemaxsizelowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for file.max_size (64kb pages)</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>filemaxsizeupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for file.max_size (64kb pages)</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>host</strong></span> </td><td>String</td><td>Target TCP/IP host or host range for create connection rules</td><td>CREATE CONNECTION</td></tr><tr><td> <span class="command"><strong>exclusive</strong></span> </td><td>Boolean</td><td>Indicate s the presence of an <em class="parameter"><code>exclusive</code></em> flag</td><td>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</td></tr><tr><td> <span class="command"><strong>pagefactorlowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for size of a page in paged queue</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>pagefactorupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for size of a page in paged queue</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>pageslowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for number of paged queue pages in memory</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>pagesupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for number of paged queue pages in memory</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>paging</strong></span> </td><td>Boolean</td><td>Indicates if the queue is a paging queue</td><td>CREAT E QUEUE</td></tr><tr><td> <span class="command"><strong>policytype</strong></span> </td><td>String</td><td>"ring", "self-destruct", "reject"</td><td>CREATE QUEUE, ACCESS QUEUE, DELETE QUEUE</td></tr><tr><td> <span class="command"><strong>queuename</strong></span> </td><td>String</td><td>Name of the target queue</td><td>ACCESS EXCHANGE, BIND EXCHANGE, MOVE QUEUE, UNBIND EXCHANGE</td></tr><tr><td> <span class="command"><strong>queuemaxsizelowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for queue.max_size (memory bytes)</td><td>CREATE QUEUE, ACCESS QUEUE</td></tr><tr><td> <span class="command"><strong>queuemaxsizeupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for queue.max_size (memory bytes)</td><td>CREATE QUEUE, ACCESS QUEUE</td></tr><tr><td> <span class="command"><strong>queuemaxcountlowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for queue.max_count (messages)</td><td>CREATE QUEUE, ACCESS QUEUE</td></tr><tr><td> <span class="co mmand"><strong>queuemaxcountupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for queue.max_count (messages)</td><td>CREATE QUEUE, ACCESS QUEUE</td></tr><tr><td> <span class="command"><strong>routingkey</strong></span> </td><td>String</td><td>Specifies routing key</td><td>BIND EXCHANGE, UNBIND EXCHANGE, ACCESS EXCHANGE, PUBLISH EXCHANGE</td></tr><tr><td> <span class="command"><strong>schemaclass</strong></span> </td><td>String</td><td>QMF schema class name</td><td>ACCESS METHOD, ACCESS QUERY</td></tr><tr><td> <span class="command"><strong>schemapackage</strong></span> </td><td>String</td><td>QMF schema package name</td><td>ACCESS METHOD</td></tr><tr><td> <span class="command"><strong>type</strong></span> </td><td>String</td><td>Type of exchange, such as topic, fanout, or xml</td><td>CREATE EXCHANGE, ACCESS EXCHANGE, DELETE EXCHANGE</td></tr></tbody></table></div></div><br class="table-break" /><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_ActionObjectPropertyTuples"></a>ACL Action-Object-Property Combinations</h5></div></div></div><p> - 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. - </p><p> - 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: - </p><pre class="programlisting"> - acl allow all access exchange - acl allow all access exchange name=abc - acl allow all access exchange name=abc durable=true -</pre><p> - These rules could possibly match one or more of the broker lookups. However, this rule - is not allowed: - </p><pre class="programlisting"> - acl allow all access exchange queuename=queue1 durable=true -</pre><p> - Properties <span class="emphasis"><em>queuename</em></span> and <span class="emphasis"><em>durable</em></span> - 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. - </p><p> - For more information about matching ACL rules please refer to - <a class="link" href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching" title="1.5.2.3. ACL Rule Matching"> - ACL Rule Matching - </a> - </p><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties"></a><p class="title"><strong>Table 1.16. Broker Lookup Events With Allowed Action, Object, and Properties</strong></p><div class="table-contents"><table border="1" summary="Broker Lookup Events With Allowed Action, Object, and Properties"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Lookup Event</th><th>Action</th><th>Object</th><th>Properties</th></tr></thead><tbody><tr><td>User querying message timestamp setting </td><td>access</td><td>broker</td><td> </td></tr><tr><td>AMQP 0-10 protocol received 'query' </td><td>access</td><td>exchange</td><td>name </td></tr><tr><td>AMQP 0-10 query binding </td><td>access</td><td>exchange</td><td>name queuename routingkey </td></tr><tr><td>AMQP 0-10 exchange declare </td><td>access</td><td>exchange</td><td>name type alternate durable autodelete </td></tr><tr>< td>AMQP 1.0 exchange access </td><td>access</td><td>exchange</td><td>name type durable </td></tr><tr><td>AMQP 1.0 node resolution </td><td>access</td><td>exchange</td><td>name </td></tr><tr><td>Management method request </td><td>access</td><td>method</td><td>name schemapackage schemaclass </td></tr><tr><td>Management agent method request </td><td>access</td><td>method</td><td>name schemapackage schemaclass </td></tr><tr><td>Management agent query </td><td>access</td><td>query</td><td>name schemaclass </td></tr><tr><td>QMF 'query queue' method </td><td>access</td><td>queue</td><td>name </td></tr><tr><td>AMQP 0-10 query </td><td>access</td><td>queue</td><td>name </td></tr><tr><td>AMQP 0-10 queue declare </td><td>access</td><td>queue</td><td>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimi t queuemaxsizeupperlimit </td></tr><tr><td>AMQP 1.0 queue access </td><td>access</td><td>queue</td><td>name alternate durable exclusive autodelete policytype queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit </td></tr><tr><td>AMQP 1.0 node resolution </td><td>access</td><td>queue</td><td>name </td></tr><tr><td>AMQP 0-10 or QMF bind request </td><td>bind</td><td>exchange</td><td>name queuename routingkey </td></tr><tr><td>AMQP 1.0 new outgoing link from exchange</td><td>bind</td><td>exchange</td><td>name queuename routingkey </td></tr><tr><td>AMQP 0-10 subscribe request </td><td>consume</td><td>queue</td><td>name </td></tr><tr><td>AMQP 1.0 new outgoing link from queue </td><td>consume</td><td>queue</td><td>name </td></tr><tr><td>TCP/IP connection creation </td><td>create</td><td>connection</td><td>host </td></tr><tr><td>Create exchange </td><td>cre ate</td><td>exchange</td><td>name type alternate durable autodelete </td></tr><tr><td>Interbroker link creation </td><td>create</td><td>link</td><td> </td></tr><tr><td>Interbroker link creation </td><td>create</td><td>link</td><td> </td></tr><tr><td>Create queue </td><td>create</td><td>queue</td><td>name alternate durable exclusive autodelete policytype paging pageslowerlimit pagesupperlimit pagefactorlowerlimit pagefactorupperlimit queuemaxcountlowerlimit queuemaxcountupperlimit queuemaxsizelowerlimit queuemaxsizeupperlimit filemaxcountlowerlimit filemaxcountupperlimit filemaxsizelowerlimit filemaxsizeupperlimit </td></tr><tr><td>Delete exchange </td><td>delete</td><td>exchange</td><td>name type alternate durable </td></tr><tr><td>Delete queue </td><td>delete</td><td>queue</td><td>name alternate durable exclusive autodelete policytype </td></tr><tr><td>Management 'mov e queue' request </td><td>move</td><td>queue</td><td>name queuename </td></tr><tr><td>AMQP 0-10 received message processing </td><td>publish</td><td>exchange</td><td>name routingkey </td></tr><tr><td>AMQP 1.0 establish sender link to queue </td><td>publish</td><td>exchange</td><td>routingkey </td></tr><tr><td>AMQP 1.0 received message processing </td><td>publish</td><td>exchange</td><td>name routingkey </td></tr><tr><td>Management 'purge queue' request </td><td>purge</td><td>queue</td><td>name </td></tr><tr><td>Management 'purge queue' request </td><td>purge</td><td>queue</td><td>name </td></tr><tr><td>Management 'redirect queue' request </td><td>redirect</td><td>queue</td><td>name queuename </td></tr><tr><td>Management 'reroute queue' request </td><td>reroute</td><td>queue</td><td>name exchangename </td></tr><tr><td>Management 'unbind exchange' request </td><td>unbind</td><td>exchange</td><td>name queuename routingkey </td></tr><tr><td>User mo difying message timestamp setting</td><td>update</td><td>broker</td><td> </td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions"></a>1.5.2.2. ACL Syntactic Conventions</h4></div></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-comments"></a>Comments</h5></div></div></div><p> - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - A line starting with the <span class="command"><strong>#</strong></span> character is considered a comment and is ignored. - </p></li><li class="listitem"><p> - Embedded comments and trailing comments are not allowed. The <span class="command"><strong>#</strong></span> is commonly found in routing keys and other AMQP literals which occur naturally in ACL rule specifications. - </p></li></ul></div><p> - </p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-whitespace"></a>White Space</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - Empty lines and lines that contain only whitespace (' ', '\f', '\n', '\r', '\t', '\v') are ignored. - </p></li><li class="listitem"><p> - Additional whitespace between and after tokens is allowed. - </p></li><li class="listitem"><p> - Group and Acl definitions must start with <span class="command"><strong>group</strong></span> and <span class="command"><strong>acl</strong></span> respectively and with no preceding whitespace. - </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-characterset"></a>Character Set</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - ACL files use 7-bit ASCII characters only - </p></li><li class="listitem"><p> - Group names may contain only - </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><span class="command"><strong>[a-z]</strong></span></li><li class="listitem"><span class="command"><strong>[A-Z]</strong></span></li><li class="listitem"><span class="command"><strong>[0-9]</strong></span></li><li class="listitem"><span class="command"><strong>'-'</strong></span> hyphen</li><li class="listitem"><span class="command"><strong>'_'</strong></span> underscore</li></ul></div><p> - </p></li><li class="listitem"><p> - Individual user names may contain only - </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><span class="command"><strong>[a-z]</strong></span></li><li class="listitem"><span class="command"><strong>[A-Z]</strong></span></li><li class="listitem"><span class="command"><strong>[0-9]</strong></span></li><li class="listitem"><span class="command"><strong>'-'</strong></span> hyphen</li><li class="listitem"><span class="command"><strong>'_'</strong></span> underscore</li><li class="listitem"><span class="command"><strong>'.'</strong></span> period</li><li class="listitem"><span class="command"><strong>'@'</strong></span> ampersand</li><li class="listitem"><span class="command"><strong>'/'</strong></span> slash</li></ul></div><p> - </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-casesensitivity"></a>Case Sensitivity</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - All tokens are case sensitive. <em class="parameter"><code>name1</code></em> is not the same as <em class="parameter"><code>Name1</code></em> and <em class="parameter"><code>create</code></em> is not the same as <em class="parameter"><code>CREATE</code></em>. - </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linecontinuation"></a>Line Continuation</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - Group lists can be extended to the following line by terminating the line with the <span class="command"><strong>'\'</strong></span> character. No other ACL file lines may be continued. - </p></li><li class="listitem"><p> - Group specification lines may be continued only after the group name or any of the user names included in the group. See example below. - </p></li><li class="listitem"><p> - Lines consisting solely of a <span class="command"><strong>'\'</strong></span> character are not permitted. - </p></li><li class="listitem"><p> - The <span class="command"><strong>'\'</strong></span> continuation character is recognized only if it is the last character in the line. Any characters after the <span class="command"><strong>'\'</strong></span> are not permitted. - </p></li></ul></div><pre class="programlisting"> - # - # 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 -</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-linelength"></a>Line Length</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> - ACL file lines are limited to 1024 characters. - </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords"></a>ACL File Keywords</h5></div></div></div> - ACL reserves several words for convenience and for context sensitive substitution. - - <div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-all"></a>The <span class="command"><strong>all</strong></span> Keyword</h6></div></div></div> - The keyword <span class="command"><strong>all</strong></span> is reserved. It may be used in ACL rules to match all individuals and groups, all actions, or all objects. - <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">acl allow all create queue</li><li class="listitem">acl allow bob@QPID all queue</li><li class="listitem">acl allow bob@QPID create all</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntactic_Conventions-keywords-userdomain"></a>User Name and Domain Name Keywords</h6></div></div></div><p> - 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. - </p><p> - Symbol substitution is allowed in the ACL file anywhere that text is supplied for a property value. - </p><p> - In the following table an authenticated user named bob.u...@qpid.com has his substitution keywords expanded. - - </p><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_UsernameSubstitution"></a><p class="title"><strong>Table 1.17. ACL User Name and Domain Name Substitution Keywords</strong></p><div class="table-contents"><table border="1" summary="ACL User Name and Domain Name Substitution Keywords"><colgroup><col /><col /></colgroup><thead><tr><th>Keyword</th><th>Expansion</th></tr></thead><tbody><tr><td> <span class="command"><strong>${userdomain}</strong></span> </td><td>bob_user_QPID_COM</td></tr><tr><td> <span class="command"><strong>${user}</strong></span> </td><td>bob_user</td></tr><tr><td> <span class="command"><strong>${domain}</strong></span> </td><td>QPID_COM</td></tr></tbody></table></div></div><p><br class="table-break" /> - </p><p> - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="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. - </li><li class="listitem"> - The Acl processing matches ${userdomain} before matching either ${user} or ${domain}. Rules that specify the combination ${user}_${domain} will never match. - </li></ul></div><p> - </p><pre class="programlisting"> - # 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 -</pre></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards"></a>Wildcards</h5></div></div></div> - ACL privides two types of wildcard matching to provide flexibility in writing rules. - - <div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-asterisk"></a>Property Value Wildcard</h6></div></div></div><p> - Text specifying a property value may end with a single trailing <span class="command"><strong>*</strong></span> 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 - </p><p> - </p><pre class="programlisting"> acl allow bob@QPID create queue name=bob*</pre><p> - </p><p> - allow user bob@QPID to create queues named bob1, bob2, bobQueue3, and so on. - </p></div><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Syntatic_Conventions-wildcards-topickey"></a>Topic Routing Key Wildcard</h6></div></div></div><p> - 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. - </p><p> - Routing keys are hierarchical where each level is separated by a period: - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">weather.usa</li><li class="listitem">weather.europe.germany</li><li class="listitem">weather.europe.germany.berlin</li><li class="listitem">company.engineering.repository</li></ul></div><p> - </p><p> - Within the routing key hierarchy two wildcard characters are defined. - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><span class="command"><strong>*</strong></span> matches one field</li><li class="listitem"><span class="command"><strong>#</strong></span> matches zero or more fields</li></ul></div><p> - </p><p> - Suppose an ACL rule file is: - </p><p> - </p><pre class="programlisting"> - acl allow-log uHash1@COMPANY publish exchange name=X routingkey=a.#.b - acl deny all all - </pre><p> - </p><p> - When user uHash1@COMPANY attempts to publish to exchange X the ACL will return these results: - - </p><div class="table"><a id="tabl-Messaging_User_Guide-ACL_Syntax-ACL_TopicExchangeMatch"></a><p class="title"><strong>Table 1.18. Topic Exchange Wildcard Match Examples</strong></p><div class="table-contents"><table border="1" summary="Topic Exchange Wildcard Match Examples"><colgroup><col /><col /></colgroup><thead><tr><th>routingkey in publish to exchange X</th><th>result</th></tr></thead><tbody><tr><td> <span class="command"><strong>a.b</strong></span> </td><td>allow-log</td></tr><tr><td> <span class="command"><strong>a.x.b</strong></span> </td><td>allow-log</td></tr><tr><td> <span class="command"><strong>a.x.y.zz.b</strong></span> </td><td>allow-log</td></tr><tr><td> <span class="command"><strong>a.b.</strong></span> </td><td>deny</td></tr><tr><td> <span class="command"><strong>q.x.b</strong></span> </td><td>deny</td></tr></tbody></table></div></div><p><br class="table-break" /> - - </p></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching"></a>1.5.2.3. ACL Rule Matching</h4></div></div></div><p> - The minimum matching criteria for ACL rules are: - </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">An actor (individually named or group member)</li><li class="listitem">An action</li><li class="listitem">An object</li></ul></div><p> - </p><p> - If a rule does not match the minimum criteria then that rule does not control the ACL allow or deny decision. - </p><p> - 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. - </p><p> - The following illustration shows how ACL rules are processed to find matching rules. -</p><pre class="programlisting"> - # 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'. - # -</pre><p> - </p><p> - Referring to <a class="link" href="chap-Messaging_User_Guide-Security.html#tabl-Messaging_User_Guide-ACL_Syntax-ACL_ActionObject_properties" title="Table 1.16. Broker Lookup Events With Allowed Action, Object, and Properties">ACL Properties Allowed for each Action and Object table</a> observe that some Action/Object pairs have different sets of allowed properties. For example different broker ACL lookups for <span class="emphasis"><em>access exchange</em></span> have different property subsets. - </p><pre class="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 -</pre><p> - If an ACL rule specifies the <span class="emphasis"><em>autodelete</em></span> 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. - </p><pre class="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 -</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Permissions"></a>1.5.2.4. Specifying ACL Permissions</h4></div></div></div><p> - Now that we have seen the ACL syntax, we will provide representative examples and guidelines for ACL files. - </p><p> - Most ACL files begin by defining groups: - </p><pre class="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 -</pre><p> - Rules in an ACL file grant or deny specific permissions to users or groups: - </p><pre class="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 -</pre><p> - In the previous example, the last line, <code class="literal">acl deny all all</code>, 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 <code class="literal">acl allow all all</code> in the last line. - </p><p> - ACL allows specification of conflicting rules. Be sure to specify the most specific rules first followed by more general rules. Here is an example: - </p><p> -</p><pre class="programlisting"> - group users alice@QPID bob@QPID charlie@QPID - acl deny charlie@QPID create queue - acl allow users create queue - acl deny all all -</pre><p> - </p><p> - 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. - </p><p> - Do not allow <em class="parameter"><code>guest</code></em> to access and log QMF management methods that could cause security breaches: - </p><pre class="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 -</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="sect-Messaging_User_Guide-Authorization-Auditing_ACL_Settings"></a>1.5.2.5. Auditing ACL Settings</h4></div></div></div><p> - 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. - </p><pre class="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 -</pre><p> - When this file is loaded it will show the following (truncated, formatted) Info-level log. - </p><pre class="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 -</pre><p> - 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. - </p><p> - 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. - </p><p> - 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. - </p><pre class="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 -</pre><p> - The previous illustration is interesting because it shows the settings as the <span class="emphasis"><em>all</em></span> keywords are - being expanded. However, that does not show the information about what is actually going into the ACL lookup tables. - </p><p> - 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. - </p><pre class="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 () -</pre><p> - 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. - </p><p> - Note that rules identified by <span class="emphasis"><em>User: *</em></span> are the rules in effect - for users otherwise unnamed in the ACL file. - </p><pre class="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{ na
<TRUNCATED> --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
