<?xml version="1.0"?>
<!--
  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.    
-->
<document>

 <properties>
  <title>Apache James Server 3 - Users Configuration</title>
 </properties>

<body>

  <section name="Users Repositories">
  
    <subsection name="Introduction">
  
      <p>User repositories are required to store James user information and authentication data</p>
  
      <p>Consult <a href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/usersrepository-template.xml">usersrepository.xml</a> in SVN to get some examples and hints.</p>
      
    </subsection>
    
    <subsection name="JPA Users Repository">
  
     <p>JPA (database via OpenJPA) based user repository. This is the default implementation.</p>
     
     <p>The usersrepository tag as 2 attributes: name="LocalUsers" and class="org.apache.james.user.file.UsersFileRepository"></p>

      <dl>
        <dt><strong>algorithm</strong></dt>
        <dd>Algorithm to has passwords. Supported password algorithm are: MD5, SHA-256, SHA-512, NONE</dd>
        <dt><strong>enableVirtualHosting</strong></dt>
        <dd>true (default) or false. Defines if the usernames must (true) or may not contain (false) a domain part (user@domain.tld).</dd>
      </dl>

    </subsection>

    <subsection name="File Users Repository">
  
      <p>The File UsersRepository implementations below are DEPRECATED and will get removed in the next release</p>
      <p>It just listed here for backward-compatibility</p>

      <p>File-based user repositories  Use these configurations to store user info in the filesystem.</p>
      
     <p>The usersrepository tag as 2 attributes:name="LocalUsers" class="org.apache.james.user.file.UsersFileRepository"></p>

      <dl>
        <dt><strong>destination</strong></dt>
        <dd>Example: file://var/users/.</dd>
        <dt><strong>ignoreCase</strong></dt>
        <dd>true or false.</dd>
        <dt><strong>enableAliases</strong></dt>
        <dd>true or false.</dd>
        <dt><strong>enableForwarding</strong></dt>
        <dd>true or false.</dd>
        <dt><strong>enableVirtualHosting</strong></dt>
        <dd>true (default) or false. Defines if the usernames must (true) or may not contain (false) a domain part (user@domain.tld).</dd>
      </dl>

    </subsection>

    <subsection name="JDBC Users Repository">
    
      <p>The JDBC UsersRepository implementations below are DEPRECATED and will get removed in the next release.</p>
      <p>It just listed here for backward-compatibility.</p>

    </subsection>

    <subsection name="LDAP Users Repository">
    
       <p>Read-Only LDAP based UsersRepository</p>
     
       <p>Example:</p>

       <source>
&lt;repository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389" 
    principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"/&gt;</source>

<!--   
      <p>This section explains how to enable Apache James Server to use an LDAP directory as a
        Users Repository.</p>
    
      <p>We have tried to make the LDAP implementation of UsersRepository as
        flexible a possible, recognising that each installation will have a unique
        directory schema.</p>
        
      <p>We assume that all users that a James Mailserver will handle fall
          within one single-rooted tree. The root of this tree, ie the lowest node
          in the directory which is an ancestor for all users served by this
          mailserver and the mailserver, is called the LDAPRoot. (See diagram)</p>

      <p>It is entirely possible that an organization may have more than one
          mail server. Consequently, the fact that a user is in the Directory does
          not imply that this mailserver should handle mail for them.</p>

      <p>This implementation of UsersRepository creates one node (object) for
          each set of mail users. The set called 'LocalUsers' is the set of users
          whose mail is handled by this server. Other sets include any mail-lists
          handled by the server. Each member of a set is recorded as an attribute
          of these objects. These nodes are child nodes of the mailserver.</p>

       <p>The mailserver will accept mail for local delivery if the user part of
          the email address matches a member of LocalUsers and if the domain/host
          part of the email address matches the first servername .
          (Set servernames autodetect to false and enter the domain served as the
          first servername, e.g. apache.org).</p>

       <p>For POP3 authentication, the mailserver first finds the user entry in
          the directory, underLDAPRoot, whose attribute, specified as
          MailAttribute in conf, matches user@domain. The mailserver authenticates
          the POP3 user if it can bind to the directory as that user entry with
          the offered password.</p>

       <p>This implementation does not set passwords in the directory. Use a dummy
          password when invoking adduser in RemoteManger.</p>

       <p>If ManageGroupAttribute is set to TRUE (as it is by default), then the
          RemoteManger will add/remove the full DN of the email group to/from the
          user entry. This facilty allows users to ask the directory what is my
          mailserver and what email lists am I subscribed to?</p>
    
      <table cellspacing="0">
        <tr>
          <td> </td>
          <td align="center">Root of Directory
            <br>Example: dc=org</br>
            <br>May not be referenced in conf.xml</br>
            <br>|</br>
            <br>|</br>
          </td>
          <td> </td>
        </tr>
        <tr>
          <td colspan="3" align="center"> - - - - - - - - - - -</td>
        </tr>
        <tr>
          <td align="center" valign="top">|
            <br>Subtree not served by James</br>
            <br> e.g.: dc=w3c, dc=org</br>
           </td>
          <td align="center" valign="top">|
            <br>Subtree served by James</br>
            <br> e.g.: dc=apache, dc=org </br>
            <br>"LDAPRoot"</br>
            <br>|</br>
          </td>
          <td align="center" valign="top">|
            <br>Subtree not served by James</br>
            <br> e.g.: dc=xml, dc=org</br>
          </td>
        </tr>
        <tr>
          <td> </td>
          <td>
            <table cellspace="0">
              <tr>
                <td colspan="4" align="center"> - - - - - - - - - - - - - - - - - - - - - - - - - -</td>
              </tr>
              <tr>
                <td align="center" valign="top">|
                  <br>This mailserver </br>
                  <br>cn=mailserver.apache.org</br>
                  <br>|</br>
                  <br> - - - - - - - -</br>
                </td>
                <td align="center" valign="top">|
                  <br>A user </br>
                  <br>cn=King Arthur</br>
                  <br> memberOfGroup=</br>
                  <br>cn=LocalUsers etc</br>
                </td>
                <td align="center" valign="top">|
                  <br>A user </br>
                  <br>cn=Morgan LeFay </br>
                </td>
                <td align="center" valign="top">|
                 <br>Another mailserver </br>
                 <br>cn=oldmail.apache.org</br>
                </td>
              </tr>
              <tr>
                <td>
                  <table cellspace="0">
                <tr>
                  <td align="center" valign="top"> |
                    <br>LocalUsers</br>
                    <br>member=Arthur</br>
                  </td>
                  <td align="center" valign="top"> |
                        <br>list-james</br>
                        <br>member=Arthur</br>
                      </td>
                </tr>
              </table>
                </td>
                <td> </td>
                <td> </td>
                <td> </td>
              </tr>
            </table>
          </td>
          <td> </td>
        </tr>
      </table>
-->
<!-- 
      <p>Six entries in JAMES.xml.xml must be set for this to work:
        <ul>
          <li>change usersManager - type to ldap.</li>
          <li>Set the ldapServer element to point to the correct host and port</li>
          <li>Set LDAPRoot and ThsServerRDN.</li>
          <li>Set the direcory FDN and password that should be used to write to the directory.</li>
          <li>Unless all your users have email addresses of the form, name@the-machine-running-James, set servernames-autodetect to false and apecify the your email domain as the first servername.</li>
        </ul>
      </p>
-->    
     </subsection>

  </section>

</body>

</document>
