Index: docs/config/realm.xml
===================================================================
--- docs/config/realm.xml	(revision 1245889)
+++ docs/config/realm.xml	(working copy)
@@ -79,7 +79,52 @@
         <p>Java class name of the implementation to use.  This class must
         implement the <code>org.apache.catalina.Realm</code> interface.</p>
       </attribute>
+      
+                  
+      <attribute name="x509UserNameRetrieverConfiguration" required="false">
+        <p>The value is used to configure how to get the user name during the client certificate authentication. 
+        The user name is the unique part of information from the client certificate that used to identify the identity of the user. 
+The Subject field (also called Subject Distinguish Name or SubjectDN) identifies the entity associated with the public key.
+The Subject field contains the following relevant attributes (it can also contain other attributes).
+</p>
+<p>
+ <table>
+    <tr><th>Subject Attribute</th><th>Subject Attribute Description</th><th>Example</th></tr>
+    <tr><td>CN</td><td>Common Name</td><td>CN=Bob BobFamily</td></tr>
+    <tr><td>emailAddress</td><td>Email Address</td><td>emailAddress=bob@example.com</td></tr>
+    <tr><td>C</td><td>Country Name</td><td>C=US</td></tr>
+    <tr><td>ST</td><td>State or Province Name</td><td>ST=NY</td></tr>
+    <tr><td>L</td><td>Locality Name</td><td>L=New York</td></tr>
+    <tr><td>O</td><td>Organization Name</td><td>O=Work Organization</td></tr>
+    <tr><td>OU</td><td>Organizational Unit Name</td><td>OU=Managers</td></tr>
+  </table>
+</p>  
+<p>  
+To retrieve the user name from the subject, you can use the entire SubjectDN field or the SubjectDN attribute.
+To retrieve the user name from entire SubjectDN field leave the value empty.
+To retrieve the user name from the SubjectDN attribute, please provide the retrieve attribute name.
+The the retrieve attribute name is a code letter based on a legend defined in the certificate itself.
+</p>  
 
+<p>  
+For example, the Email attribute is used to hold the User Name.
+Please provide "e" or "emailAddress" for the constructor.
+</p>
+
+<p>  
+For example, the Common Name attribute is used to hold the User Name.
+Please provide "CN" for the constructor.</p>
+
+ 
+      </attribute>
+
+      <attribute name="x509UserNameRetrieverClassName" required="false">
+        <p>The Java class name that is used to override the default X509UserNameRetriever. 
+        The X509UserNameRetriever is used to get the user name during the client certificate authentication.
+        If the value is provided a realm will create X509UserNameRetriever from the provided class. 
+        This class must implement the <code>org.apache.catalina.realm.X509UserNameRetriever</code> interface.</p>
+      </attribute>
+
     </attributes>
 
   </subsection>