QPID-3722 : Tidy up the document generation. Split docs by book, remove monolithic book, use makefile to build

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1330925 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 117 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/Configuring-Management-Users.xml b/qpid/doc/book/src/java-broker/Configuring-Management-Users.xml
new file mode 100644
index 0000000000..a2a8d46d88
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Configuring-Management-Users.xml
@@ -0,0 +1,117 @@
+<?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>