diff options
Diffstat (limited to 'doc/book/src/java-broker/Add-New-Users.xml')
| -rw-r--r-- | doc/book/src/java-broker/Add-New-Users.xml | 237 |
1 files changed, 0 insertions, 237 deletions
diff --git a/doc/book/src/java-broker/Add-New-Users.xml b/doc/book/src/java-broker/Add-New-Users.xml deleted file mode 100644 index dc34bcc5c9..0000000000 --- a/doc/book/src/java-broker/Add-New-Users.xml +++ /dev/null @@ -1,237 +0,0 @@ -<?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> - Add New Users - </title><para> - The Qpid Java Broker has a single reference source (<xref linkend="qpid_PrincipalDatabase"/>) that - defines all the users in the system. - </para><para> - To add a new user to the broker the password file must be - updated. The details about adding entries and when these updates - take effect are dependent on the file format each of which are - described below. - </para> - - <section role="h2" id="AddNewUsers-AvailablePasswordfileformats"><title> - Available - Password file formats - </title> - <para> - There are currently two different file formats available for use - depending on the PrincipalDatabase that is desired. In all cases - the clients need not be aware of the type of PrincipalDatabase in - use they only need support the SASL mechanisms they provide. - </para><itemizedlist> - <listitem><para> - <xref linkend="AddNewUsers-Plain"/> - </para></listitem> - <listitem><para> - <xref linkend="AddNewUsers-Base64MD5PasswordFileFormat"/> - </para></listitem> - </itemizedlist><para> - - </para> - - <section role="h3" id="AddNewUsers-Plain"><title> - Plain - </title> - <para> - The plain file has the following format: - </para> - <programlisting> -# Plain password authentication file. -# default name : passwd -# Format <username>:<password> -#e.g. -martin:password -</programlisting> - <para> - As the contents of the file are plain text and the password is - taken to be everything to the right of the ':'(colon). The - password, therefore, cannot contain a ':' colon, but this can be - used to delimit the password. - </para><para> - Lines starting with a '#' are treated as comments. - </para> -<!--h3--></section> - - <section role="h3" id="AddNewUsers-Whereisthepasswordfileformybroker-3F"><title> - Where is - the password file for my broker ? - </title> - <para> - The location of the password file in use for your broker is as - configured in your config.xml file. - </para> - <programlisting> -<principal-databases> - <principal-database> - <name>passwordfile</name> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </principal-databases> -</programlisting> - <para> - So in the example config.xml file this password file lives in the - directory specified as the conf directory (at the top of your - config.xml file). - </para><para> - If you wish to use Base64 encoding for your password file, then - in the <class> element above you should specify - org.apache.qpid.server.security.auth.database.Base64MD5PasswordFilePrincipalDatabase - </para><para> - The default is: - </para> - <programlisting> - <conf>${prefix}/etc</conf> -</programlisting> -<!--h3--></section> - - - <section role="h3" id="AddNewUsers-Base64MD5PasswordFileFormat"><title> - Base64MD5 - Password File Format - </title> - <para> - This format can be used to ensure that SAs cannot read the plain - text password values from your password file on disk. - </para><para> - The Base64MD5 file uses the following format: - </para> - <programlisting> -# Base64MD5 password authentication file -# default name : qpid.passwd -# Format <username>:<Base64 Encoded MD5 hash of the users password> -#e.g. -martin:X03MO1qnZdYdgyfeuILPmQ== -</programlisting> - <para> - As with the Plain format the line is delimited by a ':'(colon). - The password field contains the MD5 Hash of the users password - encoded in Base64. - </para><para> - This file is read on broker start-up and is not re-read. - </para> -<!--h3--></section> - - <section role="h3" id="AddNewUsers-HowcanIupdateaBase64MD5passwordfile-3F"><title> - How can - I update a Base64MD5 password file ? - </title> - <para> - To update the file there are two options: - </para><orderedlist> - <listitem><para>Edit the file by hand using the <emphasis>qpid-passwd</emphasis> tool - that will generate the required lines. The output from the tool - is the text that needs to be copied in to your active password - file. This tool is located in the broker bin directory. - Eventually it is planned for this tool to emulate the - functionality of <xref linkend="qpid_htpasswd"/> - for qpid passwd files. - <emphasis>NOTE:</emphasis> For the changes to be seen by the broker you must - either restart the broker or reload the data with the - management tools (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>) - </para></listitem> - <listitem><para>Use the management tools to create a new user. The changes - will be made by the broker to the password file and the new user - will be immediately available to the system (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>). - </para></listitem> - </orderedlist> -<!--h3--></section> -<!--h2--></section> - - - <section role="h2" id="AddNewUsers-Dynamicchangestopasswordfiles."><title> - Dynamic - changes to password files. - </title> - <para> - The Plain password file and the Base64MD5 format file are both - only read once on start up. - </para><para> - To make changes dynamically there are two options, both require - administrator access via the Management Console (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>) - </para><orderedlist> - <listitem><para>You can replace the file and use the console to reload its - contents. - </para></listitem> - <listitem><para>The management console provides an interface to create, - delete and amend the users. These changes are written back to the - active password file. - </para></listitem> - </orderedlist> -<!--h2--></section> - - <section role="h2" id="AddNewUsers-HowpasswordfilesandPrincipalDatabasesrelatetoauthenticationmechanisms"><title> - How password files and PrincipalDatabases relate to - authentication mechanisms - </title> - <para> - For each type of password file a PrincipalDatabase exists that - parses the contents. These PrincipalDatabases load various SASL - mechanism based on their supportability. e.g. the Base64MD5 file - format can't support Plain authentication as the plain password - is not available. Any client connecting need only be concerned - about the SASL module they support and not the type of - PrincipalDatabase. So I client that understands CRAM-MD5 will - work correctly with a Plain and Base64MD5 PrincipalDatabase. - </para><table> - <title>File Format and Principal Database</title><tgroup cols="2"> - <tbody> - <row> - <entry> - FileFormat/PrincipalDatabase - </entry> - <entry> - SASL - </entry> - </row> - <row> - <entry> - Plain - </entry> - <entry> - AMQPLAIN PLAIN CRAM-MD5 - </entry> - </row> - <row> - <entry> - Base64MD5 - </entry> - <entry> - CRAM-MD5 CRAM-MD5-HASHED - </entry> - </row> - </tbody> - </tgroup></table><para> - For details of SASL support see <xref linkend="qpid_Qpid-Interoperability-Documentation"/> - </para> -<!--h2--></section> - -</section> |