doc/book/src/java-broker/Configuring-Management-Users.xml

<?xml version="1.0" encoding="utf-8"?>

<!--
 
 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><title>
      Configuring Management Users
    </title><para>
            The Qpid Java broker has a single source of users for the system.
            So a user can connect to the broker to send messages and via the
            JMX console to check the state of the broker.
          </para><para>
            
          </para>

	  <section role="h2" id="ConfiguringManagementUsers-Addinganewmanagementuser"><title>
            Adding
            a new management user
          </title>
	  <para>
            The broker does have some minimal configuration available to
            limit which users can connect to the JMX console and what they
            can do when they are there.
          </para><para>
            There are two steps required to add a new user with rights for
            the JMX console.
          </para><orderedlist>
            <listitem><para>Create a new user login, see HowTo:<xref linkend="qpid_Add-New-Users"/>
            </para></listitem>
            <listitem><para>Grant the new user permission to the JMX Console
            </para></listitem>
          </orderedlist>

	  <section role="h3" id="ConfiguringManagementUsers-GrantingJMXConsolePermissions"><title>
            Granting
            JMX Console Permissions
          </title>
	  <para>
            By default new users do not have access to the JMX console. The
            access to the console is controlled via the file
            <emphasis>jmxremote.access</emphasis>.
          </para><para>
            This file contains a mapping from user to privilege.
          </para><para>
            There are three privileges available:
          </para><orderedlist>
            <listitem><para>readonly - The user is able to log in and view queues but not
            make any changes.
            </para></listitem>
            <listitem><para>readwrite - Grants user ability to read and write queue
            attributes such as alerting values.
            </para></listitem>
            <listitem><para>admin - Grants the user full access including ability to edit
            Users and JMX Permissions in addition to readwrite access.
            </para></listitem>
          </orderedlist><para>
            This file is read at start up and can forcibly be reloaded by an
            admin user through the management console.
          </para>
<!--h3--></section>

	  <section role="h3" id="ConfiguringManagementUsers-AccessFileFormat"><title>
            Access
            File Format
          </title>
	  <para>
            The file is a standard Java properties file and has the following
            format
          </para>
            <programlisting>
&lt;username&gt;=&lt;privilege&gt;
</programlisting>
          <para>
            If the username value is not a valid user (list in the specified
            PrincipalDatabase) then the broker will print a warning when it
            reads the file as that entry will have no meaning.
          </para><para>
            Only when the the username exists in both the access file and the
            PrincipalDatabase password file will the user be able to login
            via the JMX Console.
          </para><section role="h4" id="ConfiguringManagementUsers-ExampleFile"><title>
            Example File
          </title>
	  <para>
            The file will be timestamped by the management console if edited
            through the console.
          </para>
            <programlisting>
#Generated by JMX Console : Last edited by user:admin
#Tue Jun 12 16:46:39 BST 2007
admin=admin
guest=readonly
user=readwrite
</programlisting>

<!--h4--></section>
<!--h3--></section>
<!--h2--></section>
</section>