LDAPAccountManager/lam/docs/manual-sources/howto.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<book>
  <title>LDAP Account Manager - Manual</title>

  <preface>
    <title>Overview</title>

    <para>LDAP Account Manager (LAM) manages user, group and host accounts in
    an LDAP directory. LAM runs on any webserver with PHP5 support and
    connects to your LDAP server unencrypted or via SSL/TLS.</para>

    <para>Currently LAM supports these account types: Samba 3, Unix, Kolab 2,
    address book entries, NIS mail aliases and MAC addresses. There is a tree
    viewer included to allow access to the raw LDAP attributes. You can use
    templates for account creation and use multiple configuration profiles.
    LAM is translated to Catalan, Chinese (Traditional + Simplified), Czech,
    Dutch, English, French, German, Hungarian, Italian, Japanese, Polish,
    Portuguese, Russian and Spanish.</para>

    <para><ulink
    url="http://www.ldap-account-manager.org/">http://www.ldap-account-manager.org/</ulink></para>

    <para>Copyright (C) 2003 - 2010</para>

    <simplelist>
      <member>Michael Duergner &lt;michael@duergner.com&gt;</member>

      <member>Roland Gruber &lt;post@rolandgruber.de&gt;</member>

      <member>Tilo Lutz &lt;tilolutz@gmx.de&gt;</member>
    </simplelist>

    <para><emphasis role="bold">Key features:</emphasis></para>

    <itemizedlist>
      <listitem>
        <para>managing user/group/host/domain entries</para>
      </listitem>

      <listitem>
        <para>account profiles</para>
      </listitem>

      <listitem>
        <para>account creation via file upload</para>
      </listitem>

      <listitem>
        <para>multiple configuration profiles</para>
      </listitem>

      <listitem>
        <para>LDAP browser</para>
      </listitem>

      <listitem>
        <para>schema browser</para>
      </listitem>

      <listitem>
        <para>OU editor</para>
      </listitem>

      <listitem>
        <para>PDF export for all accounts</para>
      </listitem>

      <listitem>
        <para>manage user/group Quota and create home directories</para>
      </listitem>
    </itemizedlist>

    <para><emphasis role="bold">Requirements:</emphasis></para>

    <simplelist>
      <member>PHP5 (&gt;= 5.1)</member>

      <member>Openldap (2.0 or greater)</member>

      <member>A web browser that supports CSS and JavaScript</member>
    </simplelist>

    <para>The default password to edit the configuration options is
    "lam".</para>

    <para><emphasis role="bold">License:</emphasis></para>

    <para>LAM is published under the GNU General Public License. The complete
    list of licenses can be found in the copyright file.</para>

    <para><emphasis role="bold">Default password:</emphasis></para>

    <para>The default password for the LAM configuration is "lam".</para>

    <literallayout>
Have fun!
     The LAM development team</literallayout>
  </preface>

  <preface>
    <title>Architecture</title>

    <para>There are basically two groups of users for LAM:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">LDAP administrators and support
        staff:</emphasis></para>

        <para>These people administer LDAP entries like user accounts, groups,
        ...</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Users:</emphasis></para>

        <para>This includes all people who need to manage their own data
        inside the LDAP directory. E.g. these people edit their contact
        information with LAM self service (LAM Pro).</para>
      </listitem>
    </itemizedlist>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/lam_architecture.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>Therefore, LAM is split into two separate parts, LAM for admins and
    for users. LAM for admins allows to manage various types of LDAP entries
    (e.g. users, groups, hosts, ...). It also contains tools like batch
    upload, account profiles, LDAP schema viewer and an LDAP browser. LAM for
    users focuses on end users. It provides a self service for the users to
    edit their personal data (e.g. contact information). The LAM administrator
    is able to specify what data may be changed by the users. The design is
    also adaptable to your corporate design.</para>

    <para>LAM for admins/users is accessible via HTTP(S) by all major web
    browsers (Firefox, IE, Opera, ...).</para>

    <para><emphasis role="bold">LAM runtime environment:</emphasis></para>

    <para>LAM runs on PHP. Therefore, it is independant of CPU architecture
    and operating system (OS). You can run LAM on any OS which supports Apache
    or other PHP compatible web servers.</para>

    <para><emphasis role="bold">Home directory server:</emphasis></para>

    <para>You can manage user home directories and their quotas inside LAM.
    The home directories may reside on the server where LAM is installed or
    any remote server. The commands for home directory management are secured
    by SSH. LAM will use the user name and password of the logged in LAM
    administrator for authentication.</para>

    <para><emphasis role="bold">LDAP directory:</emphasis></para>

    <para>LAM connects to your LDAP server via standard LDAP protocol. It also
    supports encrypted connections with SSL and TLS.</para>
  </preface>

  <chapter id="a_installation">
    <title>Installation</title>

    <section id="a_install">
      <title>New installation</title>

      <section>
        <title>Requirements</title>

        <para>LAM has the following requirements to run:</para>

        <itemizedlist>
          <listitem>
            <para>Apache webserver (SSL recommended) with PHP module (PHP 5
            (&gt;= 5.1) with ldap, gettext, xml and optional mcrypt)</para>
          </listitem>

          <listitem>
            <para>Some LAM plugins may require additional PHP extensions (you
            will get a note on the login page if something is missing)</para>
          </listitem>

          <listitem>
            <para>Perl (optional, needed only for lamdaemon)</para>
          </listitem>

          <listitem>
            <para>OpenLDAP (&gt;2.0)</para>
          </listitem>

          <listitem>
            <para>A web browser :-)</para>
          </listitem>
        </itemizedlist>

        <para>MCrypt will be used to store your LDAP password encrypted in the
        session file.</para>

        <para>See <link linkend="a_schema">LDAP schema fles</link> for
        information about used LDAP schema files.</para>
      </section>

      <section>
        <title>Prepackaged releases</title>

        <para>LAM is available as prepackaged version for various
        platforms.</para>

        <section>
          <title>Debian</title>

          <informaltable frame="none" tabstyle="noborder">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><inlinemediaobject>
                      <imageobject>
                        <imagedata fileref="images/debian.png" />
                      </imageobject>
                    </inlinemediaobject></entry>

                  <entry>LAM is part of the official Debian repository. New
                  releases are uploaded to unstable and will available
                  automatically in testing and the stable releases. You can
                  run<literal> </literal><para><emphasis role="bold">apt-get
                  install ldap-account-manager</emphasis></para>to install LAM
                  on your server. Additionally, you may download the LAM
                  Debian packages from the <ulink type=""
                  url="http://www.ldap-account-manager.org/">LAM
                  homepage</ulink> or the <ulink
                  url="http://packages.debian.org/search?keywords=ldap-account-manager">Debian
                  package homepage</ulink>.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </section>

        <section>
          <title>Suse/Fedora</title>

          <informaltable frame="none">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><inlinemediaobject>
                      <imageobject>
                        <imagedata fileref="images/suse.png" />
                      </imageobject>
                    </inlinemediaobject><para></para><inlinemediaobject>
                      <imageobject>
                        <imagedata fileref="images/fedora.png" />
                      </imageobject>
                    </inlinemediaobject></entry>

                  <entry>There are RPM packages available on the <ulink
                  type="" url="http://www.ldap-account-manager.org/">LAM
                  homepage</ulink>. The packages can be installed with this
                  command<para><emphasis role="bold">rpm -i &lt;path to LAM
                  package&gt;</emphasis></para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </section>

        <section>
          <title>Other RPM based distributions</title>

          <para>The RPM packages for Suse/Fedora are very generic and should
          be installable on other RPM-based distributions, too. The Fedora
          packages use apache:apache as file owner and the Suse ones use
          wwwrun:www.</para>
        </section>

        <section>
          <title>FreeBSD</title>

          <informaltable frame="none">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><inlinemediaobject>
                      <imageobject>
                        <imagedata fileref="images/freebsd.png" />
                      </imageobject>
                    </inlinemediaobject></entry>

                  <entry>LAM is part of the official FreeBSD ports tree. For
                  more details see these pages:<para>FreeBSD-CVS: <ulink
                  url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/ldap-account-manager">http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/ldap-account-manager</ulink></para><para>FreshPorts:
                  <ulink
                  url="http://www.freshports.org/sysutils/ldap-account-manager">http://www.freshports.org/sysutils/ldap-account-manager</ulink></para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </section>
      </section>

      <section>
        <title>Installing the tar.gz</title>

        <section>
          <title>Extract the archive</title>

          <para>Please extract the archive with the following command:</para>

          <para>tar xzf ldap-account-manager-&lt;version&gt;.tar.gz</para>
        </section>

        <section>
          <title>Install the files</title>

          <section>
            <title>Manual copy</title>

            <para>Copy the files into the html-file scope of the web server.
            For example /apache/htdocs.</para>

            <para>Then set the appropriate file permissions:</para>

            <itemizedlist>
              <listitem>
                <para>lam/sess: write permission for apache user</para>
              </listitem>

              <listitem>
                <para>lam/tmp: write permission for apache user</para>
              </listitem>

              <listitem>
                <para>lam/config (with subdirectories): write permission for
                apache user</para>
              </listitem>

              <listitem>
                <para>lam/lib: lamdaemon.pl must be set executable (See also
                docs/readme.lamdeamon.txt)</para>
              </listitem>
            </itemizedlist>
          </section>

          <section>
            <title>With configure script</title>

            <para>Instead of manually copying files you can also use the
            included configure script to install LAM. Just run these commands
            in the extracted directory:</para>

            <itemizedlist>
              <listitem>
                <para>./configure</para>
              </listitem>

              <listitem>
                <para>make install</para>
              </listitem>
            </itemizedlist>

            <para>Options for "./configure":</para>

            <itemizedlist>
              <listitem>
                <para>--with-httpd-user=USER USER is the name of your Apache
                user account (default httpd)</para>
              </listitem>

              <listitem>
                <para>--with-httpd-group=GROUP GROUP is the name of your
                Apache group (default httpd)</para>
              </listitem>

              <listitem>
                <para>--with-web-root=DIRECTORY DIRECTORY is the name where
                LAM should be installed (default /usr/local/lam)</para>
              </listitem>
            </itemizedlist>
          </section>
        </section>

        <section>
          <title>Configuration files</title>

          <para>Copy conf/config.cfg_sample to conf/config.cfg and
          conf/lam.conf_sample to conf/lam.conf. Open the index.html in your
          web browser:</para>

          <itemizedlist>
            <listitem>
              <para>Follow the link "LAM configuration" from the start page to
              <link linkend="a_configuration">configure LAM</link>.</para>
            </listitem>

            <listitem>
              <para>Select "Edit general settings" to setup global settings
              and to change the <link linkend="a_configPasswords">master
              configuration password</link> (default is "lam").</para>
            </listitem>

            <listitem>
              <para>Select "Edit server profiles" to setup your server
              profiles. There should be the lam profile which you just copied
              from the sample file. The default password is "lam". Now change
              the settings to fit for your environment.</para>
            </listitem>
          </itemizedlist>
        </section>
      </section>

      <section>
        <title>System configuration</title>

        <section>
          <title>PHP</title>

          <para>LAM runs with PHP5 (&gt;= 5.1). Needed changes in your
          php.ini:</para>

          <para>memory_limit = 64M</para>
        </section>

        <section>
          <title>Locales for non-English translation</title>

          <para>If you want to use a translated version of LAM be sure to
          install the needed locales. The following table shows the needed
          locales for the different languages.</para>

          <table>
            <title>Locales</title>

            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><emphasis role="bold">Language</emphasis></entry>

                  <entry><emphasis role="bold">Locale</emphasis></entry>
                </row>

                <row>
                  <entry>Catalan</entry>

                  <entry>ca_ES.utf8</entry>
                </row>

                <row>
                  <entry>Chinese (Simplified)</entry>

                  <entry>zh_CN.utf8</entry>
                </row>

                <row>
                  <entry>Chinese (Traditional)</entry>

                  <entry>zh_TW.utf8</entry>
                </row>

                <row>
                  <entry>Czech</entry>

                  <entry>cs_CZ.utf8</entry>
                </row>

                <row>
                  <entry>Dutch</entry>

                  <entry>nl_NL.utf8</entry>
                </row>

                <row>
                  <entry>English</entry>

                  <entry>no extra locale needed</entry>
                </row>

                <row>
                  <entry>French</entry>

                  <entry>fr_FR.utf8</entry>
                </row>

                <row>
                  <entry>German</entry>

                  <entry>de_DE.utf8</entry>
                </row>

                <row>
                  <entry>Hungarian</entry>

                  <entry>hu_HU.utf8</entry>
                </row>

                <row>
                  <entry>Italian</entry>

                  <entry>it_IT.utf8</entry>
                </row>

                <row>
                  <entry>Japanese</entry>

                  <entry>ja_JP.utf8</entry>
                </row>

                <row>
                  <entry>Polish</entry>

                  <entry>pl_PL.utf8</entry>
                </row>

                <row>
                  <entry>Portuguese</entry>

                  <entry>pt_BR.utf8</entry>
                </row>

                <row>
                  <entry>Russian</entry>

                  <entry>ru_RU.utf8</entry>
                </row>

                <row>
                  <entry>Spanish</entry>

                  <entry>es_ES.utf8</entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para>You can get a list of all installed locales on your system by
          executing:</para>

          <para>locale -a</para>

          <para>Debian users can add locales with "dpkg-reconfigure
          locales".</para>
        </section>
      </section>
    </section>

    <section>
      <title>Upgrading LAM or migrate from LAM to LAM Pro</title>

      <section>
        <title>Migrating configuration files</title>

        <para>First, you need to make a backup of your existing configuration
        files.</para>

        <para>LAM stores all configuration files in the "config" folder.
        Please backup the following files and copy them after the new version
        is installed.</para>

        <simplelist>
          <member>config/*.conf</member>

          <member>config/config.cfg</member>

          <member>config/pdf/*.xml</member>

          <member>config/profiles/*.xml</member>
        </simplelist>

        <para>LAM Pro only:</para>

        <simplelist>
          <member>config/selfService/*.*</member>

          <member>config/passwordMailTemplate.txt</member>
        </simplelist>

        <para>Second, <link linkend="a_uninstall">uninstall</link> your
        current LAM (Pro) installation.</para>

        <para>Third, <link linkend="a_install">install</link> the new LAM
        (Pro) release. Skip the part about setting up LAM configuration
        files.</para>

        <para>Finally, restore your configuration files from the backup. Copy
        all files from the backup folder to the config folder in your LAM Pro
        installation. Do not simply replace the folder because the new LAM
        (Pro) release might include additional files in this folder. Overwrite
        any existing files with your backup files.</para>

        <para>Now open your webbrowser and point it to the LAM login page. All
        your settings should be migrated.</para>

        <para>Please check also the <link linkend="a_versUpgrade">version
        specific instructions</link>. They might include additional
        actions.</para>
      </section>

      <section id="a_versUpgrade">
        <title>Version specific upgrade instructions</title>

        <section>
          <title>2.2.0 -&gt; 2.3.0</title>

          <para><emphasis role="bold">LAM Pro:</emphasis> There is now a
          separate account type for group of (unique) names. Please edit your
          server profiles to activate the new account type.</para>
        </section>

        <section>
          <title>1.1.0 -&gt; 2.2.0</title>

          <para>No changes.</para>
        </section>
      </section>
    </section>

    <section id="a_uninstall">
      <title>Unistalltion of LAM (Pro)</title>

      <para>If you used the prepackaged installation packages then remove the
      ldap-account-manager and ldap-account-manager-lamdaemon packages.</para>

      <para>Otherwise, remove the folder where you installed LAM via configure
      or by copying the files.</para>
    </section>
  </chapter>

  <chapter id="a_configuration">
    <title>Configuration</title>

    <para>After you <link linkend="a_installation">installed</link> LAM you
    can configure it to fit your needs. The complete configuration can be done
    inside the application. There is no need to edit configuration
    files.</para>

    <para>Please point you browser to the location where you installed LAM.
    E.g. for Debian/RPM this is http://yourServer/lam. If you installed LAM
    via the tar.gz then this may vary. You should see the following
    page:</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/login.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>If you see an error message then you might need to install an
    additional PHP extension. Please follow the instructions and reload the
    page afterwards.</para>

    <para>Now you are ready to configure LAM. Click on the "LAM configuration"
    link to proceed.</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/configOverview.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>Here you can change LAM's general settings, setup server profiles
    for your LDAP server(s) and configure the <link
    linkend="a_selfService">self service</link> (LAM Pro). You should start
    with the general settings and then setup a server profile.</para>

    <section>
      <title>General settings</title>

      <para>After selecting "Edit general settings" you will need to enter the
      <link linkend="a_configPasswords">master configuration password</link>.
      The default password for new installations is "lam". Now you can edit
      the general settings.</para>

      <section>
        <title>Security settings</title>

        <para>Here you can set a time period after which inactive sessions are
        automatically invalidated. The selected value represents minutes of
        inactivity.</para>

        <para>You may also set a list of IP addresses which are allowed to
        access LAM. The IPs can be specified as full IP (e.g. 123.123.123.123)
        or with the "*" wildcard (e.g. 123.123.123.*). Users which try to
        access LAM via an untrusted IP only get blank pages.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configGeneral1.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Password policy</title>

        <para>This allows you to specify a central password policy for LAM.
        The policy is valid for all password fields inside LAM admin
        (excluding tree view) and LAM self service. Configuration passwords do
        not need to follow this policy.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configGeneral2.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>You can set the minimum password length and also the complexity
        of the passwords.</para>
      </section>

      <section>
        <title>Logging</title>

        <para>LAM can log events (e.g. user logins). You can use system
        logging (syslog for Unix, event viewer for Windows) or log to a
        separate file. Please note that LAM may log sensitive data (e.g.
        passwords) at log level "Debug". Production system should be set to
        "Warning" or "Error".</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configGeneral3.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Change master password</title>

        <para>If you would like to change the master configuration password
        then enter a new password here.</para>
      </section>
    </section>

    <section>
      <title>Server profiles</title>

      <para>The server profiles store information about your LDAP server (e.g.
      host name) and what kind of accounts (e.g. users and groups) you would
      like to manage. There is no limit on the number of server
      profiles.</para>

      <section>
        <title>Manage server profiles</title>

        <para>Select "Manage server profiles" to open the profile management
        page.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configProfiles1.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>Here you can create, rename and delete server profiles. The
        <link linkend="a_configPasswords">passwords</link> of your server
        profiles can also be reset.</para>

        <para>You may also specify the default server profile. This is the
        server profile which is preselected at the login page. It also
        specifies the language of the login and configuration pages.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configProfiles2.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>You can create a new server profile by simply entering its name
        and password. After you created a new profile you can go back to the
        profile login and edit your new server profile.</para>

        <para>All operations on the profile management page require that you
        authenticate yourself with the <link
        linkend="a_configPasswords">configuration master
        password</link>.</para>
      </section>

      <section>
        <title>Editing a server profile</title>

        <para>Please select you server profile and enter its password to edit
        a server profile.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configProfiles3.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>Each server profile contains the following information:</para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">General settings:</emphasis> general
            settings about your LDAP server (e.g. host name and security
            settings)</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Account types:</emphasis> list of
            account types (e.g. users and groups) that you would like to
            manage and type specific settings (e.g. LDAP suffix)</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Modules:</emphasis> list of modules
            which define what account aspects (e.g. Unix, Samba, Kolab) you
            would like to manage</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Module settings:</emphasis> settings
            which are specific for the selected account modules on the page
            before</para>
          </listitem>
        </itemizedlist>

        <section>
          <title>General settings</title>

          <para>Here you can specify the LDAP server and some security
          settings.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configProfiles4.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>The server address of your LDAP server can be a DNS name or an
          IP address. Use ldap:// for unencrypted LDAP connections or TLS
          encrypted connections. LDAP+SSL (LDAPS) encrypted connections are
          specified with ldaps://. The port value is optional. TLS cannot be
          combined with ldaps://.</para>

          <para>LAM includes an LDAP browser which allows direct modification
          of LDAP entries. If you would like to use it then enter the LDAP
          suffix at "Tree suffix".</para>

          <para>Some LDAP queries are internally cached by LAM. You can
          specify how long LAM should use cached data. The search limit is
          used to reduce the number of search results which are returned by
          your LDAP server.</para>

          <para>The access level specifies if LAM should allow to modify LDAP
          entries. This feature is only available in LAM Pro. LAM non-Pro
          releases use write access. See <link
          linkend="a_accessLevelPasswordReset">this page</link> for details on
          the different access levels.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configProfiles5.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>LAM is translated to many different languages. Here you can
          select the default language for this server profile. The language
          setting may be overriden at the LAM login page.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configProfiles6.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>LAM can manage user home directories and quotas with an
          external script. You can specify the home directory server and where
          the script is located. The default rights for new home directories
          can be set, too.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configProfiles7.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>LAM supports two methods for login. You may either specify a
          fixed list of LDAP DNs or let LAM search for the DN in your
          directory. E.g. if a user logs in with the user name "joe" then LAM
          will do an LDAP search for this user name. When it finds a matching
          DN then it will use this to authenticate the user. The wildcard
          "%USER%" will be replaced by "joe" in this example. This way you can
          provide login by user name, email address or other LDAP
          attributes.</para>

          <para>You may also change the password of this server
          profile.</para>
        </section>

        <section>
          <title>Account types</title>

          <para>LAM supports to manage various types of LDAP entries (e.g.
          users, groups, DHCP entries, ...). On this page you can select which
          types of entries you want to manage with LAM.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configTypes1.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>The section at the top shows a list of possible types. You can
          activate them by simply clicking on the plus sign next to it.</para>

          <para>Each account type has the following options:</para>

          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">LDAP suffix:</emphasis> the LDAP
              suffix where entries of this type should be managed</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">List attributes:</emphasis> a list
              of attributes which are shown in the account lists</para>
            </listitem>
          </itemizedlist>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configTypes2.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>On the next page you can specify in detail what extensions
          should be enabled for each account type.</para>
        </section>

        <section>
          <title>Modules</title>

          <para>The modules specify the active extensions for each account
          type. E.g. here you can setup if your user entries should be address
          book entries only or also support Unix or Samba.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configModules1.png" />
              </imageobject>
            </mediaobject>
          </screenshot>

          <para>Each account type needs a so called "base module". This is the
          basement for all LDAP entries of this type. Usually, it provides the
          structural object class for the LDAP entries. There must be exactly
          one active base module for each account type.</para>

          <para>Furthermore, there may be any number of additional active
          account modules. E.g. you may select "Personal" as base module and
          Unix + Samba as additional modules.</para>
        </section>

        <section>
          <title>Module settings</title>

          <para>Depending on the activated account modules there may be
          additional configuration options available. They can be found on the
          "Module settings" tab. E.g. the Personal account module allows to
          hide several input fields and the Unix module requires to specify
          ranges for UID numbers.</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/configSettings1.png" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </section>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>Managing entries in your LDAP directory</title>

    <para>This chapter will give you instructions how to manage the different
    LDAP entries in your directory.</para>

    <para>Please note that not all account types are manageable with the free
    LAM release. LAM Pro provides some more account types and modules to
    support additional LDAP object classes.</para>

    <para><emphasis role="bold">Additional types:</emphasis></para>

    <itemizedlist>
      <listitem>
        <para>Group of names</para>
      </listitem>

      <listitem>
        <para>Aliases</para>
      </listitem>

      <listitem>
        <para>NIS objects</para>
      </listitem>
    </itemizedlist>

    <para><emphasis role="bold">Additional modules:</emphasis></para>

    <itemizedlist>
      <listitem>
        <para>Group of names (groupOfNames)</para>
      </listitem>

      <listitem>
        <para>Group of unique names (groupOfUniqueNames)</para>
      </listitem>

      <listitem>
        <para>Unix (rfc2307bisPosixGroup)</para>
      </listitem>

      <listitem>
        <para>Alias (aliasEntry)</para>
      </listitem>

      <listitem>
        <para>User name (uidObject)</para>
      </listitem>

      <listitem>
        <para>NIS object (nisObject)</para>
      </listitem>

      <listitem>
        <para>Custom scripts (customScripts)</para>
      </listitem>
    </itemizedlist>

    <para><emphasis role="bold">Basic page layout:</emphasis></para>

    <para>After the login LAM will present you its main page. It consists of a
    header part which is equal for all pages and the content area which covers
    most the of the page.</para>

    <para>The header part includes the links to manage all account types (e.g.
    users and groups) and open the tree view (LDAP browser). There is also the
    logout link and a tools entry.</para>

    <para>When you login the you will see an account listing in the content
    area.</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/mainpage.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>Here you can create, delete and modify accounts. Use the action
    buttons at the left or double click on an entry to edit it.</para>

    <para>The suffix selection box allows you to list only the accounts which
    are located in a subtree of your LDAP directory.</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/listConfig.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>You can change the number of shown entries per page with "Change
    settings". Depending on the account type there may be additional settings.
    E.g. the user list can convert group numbers to group names.</para>

    <para>When you select to edit an entry then LAM will show all its data on
    a tabbed view. There is one tab for each functional part of the account.
    You can set default values by loading an <link
    linkend="a_accountProfile">account profile</link>.</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/editView.png" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <section>
      <title>Users</title>

      <para></para>

      <section>
        <title>Personal</title>

        <para>This module is the most common basis for user accounts in LAM.
        You can use it stand-alone to manage address book entries or in
        combination with Unix, Samba or other modules.</para>

        <para>The Personal module provides support for managing various
        personal data of your users including mail addresses and telephone
        numbers. You can also add photos of your users. If you do not need to
        manage all attributes then you can deactivate them in your server
        profile.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_personal.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Unix</title>

        <para>The Unix module manages Unix user accounts including group
        memberships.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_unixUser.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Samba 3</title>

        <para>LAM supports full Samba 3 user management including logon hours
        and terminal server options.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_samba3User1.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_samba3User2.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_samba3User3.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Kolab</title>

        <para>This module supports to manage Kolab accounts with LAM. E.g. you
        can set the user's mail quota and define invitation policies.</para>

        <para>Please enter an email address at the Personal page and set a
        Unix password first. Both are required that Kolab accepts the
        accounts.</para>

        <para>Kolab users should not be directly deleted with LAM. You can
        mark an account for deletion which then is done by the Kolab server
        itself. This makes sure that the mailbox etc. is also deleted.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_kolab.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Asterisk</title>

        <para>LAM supports Asterisk accounts, too. You can set the called ID,
        host and account context for your users.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_asterisk.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>EDU person</title>

        <para>EDU person accounts are mainly used in university networks. You
        can specify the principal name, nick names and much more.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_eduPerson.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Password policy (LAM Pro)</title>

        <para>OpenLDAP supports the <ulink
        url="http://linux.die.net/man/5/slapo-ppolicy">ppolicy</ulink> overlay
        to manage password policies for LDAP entries. LAM Pro supports <link
        linkend="a_ppolicy">managing the policies</link> and assigning them to
        user accounts.</para>

        <para>Please add the account type "Password policies" to your LAM
        server profile and activate the "Password policy" module for the user
        type.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/ppolicyUser.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>You can assign any password policy which is found in the LDAP
        suffix of the "Password policies" type. When you set the policy to
        "default" then OpenLDAP will use the default policy as defined in your
        slapd.conf file.</para>
      </section>
    </section>

    <section>
      <title>Groups</title>

      <para></para>

      <section>
        <title>Unix</title>

        <para>This module is used to manage Unix group entries. This is the
        default module to manage Unix groups and uses the nis.schema. Suse
        users who use the rfc2307bis.schema need to use LAM Pro.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_unixGroup.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Unix groups with rfc2307bis schema (LAM Pro)</title>

        <para>Some applications (e.g. Suse Linux) use the rfc2307bis schema
        for Unix accounts instead of the nis schema. In this case group
        accounts are based on the object class <link lang=""
        linkend="a_groupOfNames">groupOf(Unique)Names</link>. The object class
        is auxiliary in this case.</para>

        <para>LAM Pro supports these groups with a special account module:
        <emphasis role="bold">rfc2307bisPosixGroup</emphasis></para>

        <para>Use this module only if your system depends on the rfc2307bis
        schema. The module can be selected in the LAM configuration.</para>

        <para><screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/rfc2307bis.png" />
              </imageobject>
            </mediaobject>
          </screenshot><screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/mod_unixGroupLAMPro.png" />
              </imageobject>
            </mediaobject>
          </screenshot></para>
      </section>

      <section>
        <title>Samba 3</title>

        <para>LAM supports managing Samba 3 groups. You can set special group
        types and also create Windows predefined groups like "Domain
        admins".</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_sambaGroup.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>
    </section>

    <section>
      <title>Hosts</title>

      <section>
        <title>Samba 3</title>

        <para>You can manage Samba 3 host entries by adding the Unix and Samba
        3 account modules.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_sambaHost1.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/mod_sambaHost2.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>IP addresses (LAM Pro)</title>

        <para>You can manage the IP addresses of host accounts with the ipHost
        module. It manages the following information:</para>

        <itemizedlist>
          <listitem>
            <para>IP addresses (IPv4/IPv6)</para>
          </listitem>

          <listitem>
            <para>location of the host</para>
          </listitem>

          <listitem>
            <para>manager: the person who is responsible for the host</para>
          </listitem>
        </itemizedlist>

        <para>You can activate this extension by adding the module ipHost to
        the list of active host modules.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/ipHost.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>
    </section>

    <section id="a_groupOfNames">
      <title>Group of (unique) names (LAM Pro)</title>

      <para>These classes can be used to represent group relations. Since they
      allow DNs as members you can also use them to represent nested groups.
      Activate the account type "Group of names" in your LAM server profile to
      use these account modules.</para>

      <para>Group of (unique) names have four basic attributes:</para>

      <itemizedlist>
        <listitem>
          <para>Name: a unique name for the group</para>
        </listitem>

        <listitem>
          <para>Description: optional description</para>
        </listitem>

        <listitem>
          <para>Owner: the account which owns this group (optional)</para>
        </listitem>

        <listitem>
          <para>Members: the members of the group (at least one is
          required)</para>
        </listitem>
      </itemizedlist>

      <para>You can add any accounts as members. This includes other groups
      which leads to nested groups.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/groupOfNames1.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>Aliases (LAM Pro)</title>

      <para>Some applications use the object class "alias" to link LDAP
      entries to other parts of the LDAP tree. Activate the account type
      "Aliases" in your LAM server profile to use this account type.</para>

      <para>Currently, only user accounts can be aliased with the "uidObject"
      object class.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/alias.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>NIS objects (LAM Pro)</title>

      <para>You can manage NIS objects with LAM Pro. This allows you define
      network mount points in LDAP.</para>

      <para>Add the NIS objects type to your LAM configuration and then the
      NIS objects module. This will add the NIS objects tab to LAM.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/nisObject.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section id="a_ppolicy">
      <title>Password policies (LAM Pro)</title>

      <para>OpenLDAP supports the <ulink
      url="http://linux.die.net/man/5/slapo-ppolicy">ppolicy</ulink> overlay
      to manage password policies for LDAP entries. This allows you to set
      password policies which are independent from your applications. The
      policies are managed internally by the LDAP server.</para>

      <para>You can manage these policies with LAM Pro with the account type
      "Password policies".</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/ppolicy.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>You will need to add the ppolicy schema to your OpenLDAP
      configuration and activate the <ulink
      url="http://linux.die.net/man/5/slapo-ppolicy">ppolicy</ulink> overlay
      module in slapd.conf to use this feature.</para>
    </section>

    <section>
      <title>Custom scripts (LAM Pro)</title>

      <para>LAM Pro allows you to execute scripts whenever an account is
      created, modified or deleted. This can be useful to automate processes
      which needed manual work afterwards (e.g. sending your user a welcome
      mail or register a mailbox). To activate this feature please add the
      "Custom scripts" module to all needed account types on the configuration
      pages.</para>

      <para>You can specify multiple scripts for each action type (e.g.
      modify) and account type (e.g. user). The scripts need to be located on
      the filesystem of your webserver and will be executed in its user
      environment. E.g. if you webserver runs as user www-data with the group
      www-data then the custom scripts will be run under this user with his
      rights. The output of the scripts will be shown in LAM.</para>

      <para>You can specify the scripts on the LAM configuration pages.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/customScripts.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para><emphasis role="bold">Syntax:</emphasis></para>

      <para>Please enter one script per line. Each line has the following
      format: &lt;account type&gt; &lt;action&gt; &lt;script&gt;</para>

      <para>E.g.: user preModify /usr/bin/myCustomScript -u $uid$</para>

      <para><emphasis role="bold">Account types:</emphasis></para>

      <para>You can setup scripts for all available account types (e.g. user,
      group, host, ...). Please see the help on the configuration page about
      your current active account types.</para>

      <para><emphasis role="bold">Actions:</emphasis></para>

      <table>
        <title>Action types</title>

        <tgroup cols="2">
          <tbody>
            <row>
              <entry><emphasis role="bold">Action name</emphasis></entry>

              <entry><emphasis role="bold">Description</emphasis></entry>
            </row>

            <row>
              <entry>preCreate</entry>

              <entry>executed before creating a new account (cancels operation
              if a script returns an exit code &gt; 0)</entry>
            </row>

            <row>
              <entry>postCreate</entry>

              <entry>executed after creating a new account</entry>
            </row>

            <row>
              <entry>preModify</entry>

              <entry>executed before the account is modified (cancels
              operation if a script returns an exit code &gt; 0)</entry>
            </row>

            <row>
              <entry>postModify</entry>

              <entry>executed after an account was modified</entry>
            </row>

            <row>
              <entry>preDelete</entry>

              <entry>executed before an account was modified (cancels
              operation if a script returns an exit code &gt; 0)</entry>
            </row>

            <row>
              <entry>postDelete</entry>

              <entry>executed after an account was modified</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para><emphasis role="bold">Script:</emphasis></para>

      <para>You can execute any script which is located on the filesystem of
      your webserver. The path may be absolute or relative to the
      PATH-variable of the environment of your webserver process. It is also
      possible to add commandline arguments to your scripts. Additionally, LAM
      will resolve wildcards to LDAP attributes. If your script includes an
      wildcard in the format $ATTRIBUTE$ then LAM will replace it with the
      attribute value of the current LDAP entry. The values of multi-value
      attributes are separated by commas. E.g. if you create an account with
      the attribute "uid" and value "steve" then LAM will resolve "$uid$" to
      "steve".</para>

      <para><emphasis role="bold"></emphasis></para>

      <para>You can see a preview of the commands which will be executed on
      the "Custom scripts" tab.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/customScripts2.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>Tree view (LDAP browser)</title>

      <para>The tree view provides a raw view on your LDAP directory. This
      feature is for people who are experienced with LDAP and need special
      functionality which the LAM account modules not provide. E.g. if you
      want to add a special object class to an account or edit attributes
      ignoring LAM's syntax checks.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/tree1.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>There are also some special functions available:</para>

      <para><emphasis role="bold">Export:</emphasis> This allows you to export
      entries to a file (e.g. LDIF or CSV format).</para>

      <para><emphasis role="bold">Show internal attributes:</emphasis> Shows
      internal attributes of the current entry. This includes information
      about the creator and creation time of the entry.</para>
    </section>

    <section>
      <title>Typical usage scenarios</title>

      <para>Here is a list of typical usage scenarios and what account types
      and modules you need to configure.</para>

      <para><emphasis role="bold">Address book entries:</emphasis></para>

      <para>Account types:</para>

      <itemizedlist>
        <listitem>
          <para>Users (Personal)</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Unix accounts:</emphasis></para>

      <para>Account types: Users, Groups</para>

      <itemizedlist>
        <listitem>
          <para>Users (Personal + Unix)</para>
        </listitem>

        <listitem>
          <para>Groups (Unix (posixGroup))</para>
        </listitem>
      </itemizedlist>

      <para>Suse users may need to use Group (Group of names + Unix
      (rfc2307bisPosixGroup)) because of Suse's special LDAP schema.</para>

      <para><emphasis role="bold">Samba accounts:</emphasis></para>

      <para>Account types:</para>

      <itemizedlist>
        <listitem>
          <para>Users (Personal + User + Samba 3)</para>
        </listitem>

        <listitem>
          <para>Groups (Unix + Samba 3)</para>
        </listitem>

        <listitem>
          <para>Hosts (Account + Unix + Samba 3)</para>
        </listitem>

        <listitem>
          <para>Samba domains (Samba domain)</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Asterisk:</emphasis></para>

      <para>Account types:</para>

      <itemizedlist>
        <listitem>
          <para>Users (Personal + Asterisk)</para>
        </listitem>

        <listitem>
          <para>Asterisk extensions (Asterisk extension)</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">phpGroupWare:</emphasis></para>

      <para>Account modules:</para>

      <itemizedlist>
        <listitem>
          <para>Users (Personal + Unix + phpGroupWare)</para>
        </listitem>

        <listitem>
          <para>Groups (Unix + phpGroupWare)</para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>

  <chapter>
    <title>Tools</title>

    <para></para>

    <section id="a_accountProfile">
      <title>Profile editor</title>

      <para>The account profiles are templates for your accounts. Here you can
      specify default values which can then be loaded when you create
      accounts. You may also load a template for an existing account to reset
      it to default values. When you create a new account then LAM will always
      load the profile named <emphasis role="bold">"default"</emphasis>. This
      account profile can include default values for all your accounts.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/profileEditor.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>File upload</title>

      <para>When you need to create lots of accounts then you can use LAM's
      file upload to create them. LAM will read a CSV formatted file and
      create the related LDAP entries. Please check the data in you CSV file
      carefully. LAM will do less checks for the file upload than for single
      account creation.</para>

      <para>At the first page please select the account type and what
      extensions should be activated.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/fileUpload1.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>The next page shows all available options for the file upload. You
      will also find a sample CSV file which can be used as template for your
      CSV file. All red options are required columns in the file. You need to
      specify a value for each account.</para>

      <para>When you upload the CSV file then LAM first does some checks on
      this file. This includes syntax checks and if all required data was
      entered. No changes in the LDAP directory are done at this time.</para>

      <para>If the checks were successful then LAM will ask again if you want
      to create the accounts. You will also have the chance to check the
      upload by viewing the changes in LDIF format.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/fileUpload2.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>OU editor</title>

      <para>This is a simple editor to add/delete organisational units in your
      LDAP tree. This way you can structure the accounts.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/ouEditor.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>PDF editor</title>

      <para>All accounts in LAM may be exported as PDF files. You can specify
      the page structure and displayed information by editing the PDF
      profiles.</para>

      <para>When you export accounts to PDF then each account will get its own
      page inside the PDF. There is a headline on each page where you can show
      a page title. You may also add a logo to each page. To add more possible
      logos simply copy the images to config/pdf/logos.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/pdfEditor.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>The main part is structured into sections of information. Each
      section has a title. This can either be static text or the value of an
      attribute. You may also insert a static text block as section. Sections
      can be moved by using the arrows next to the section title.</para>

      <para>Each section can contain multiple fields which usually represent
      LDAP attributes. You can simply add new fields by selecting the field
      name and its position. Then use the arrows to move the field inside the
      section.</para>
    </section>

    <section>
      <title>Schema browser</title>

      <para>Here you browse the schema of your LDAP server. You can view what
      object classes, attributes, syntaxes and matching rules are available.
      This is useful if you need to check if a certain object class is
      available.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/schemaBrowser.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>Server information</title>

      <para>This shows some basic information about your LDAP server.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/serverInfo.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>Tests</title>

      <para>This allows you to check if your LDAP schema is compatible with
      LAM and to find possible problems.</para>

      <section>
        <title>Lamdaemon test</title>

        <para>LAM provides an external script to manage home directories and
        quotas. You can test here if everything is setup correctly.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/lamdaemonTest.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>Schema test</title>

        <para>This will test if your LDAP schema supports all object classes
        and attributes of the active LAM modules. If you get a message that
        something is missing please check that you installed all <link
        linkend="a_schema">required schemas</link>.</para>

        <para>If you get error messages about object class violations then
        this test can tell you what is missing.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/schemaTest.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>
    </section>
  </chapter>

  <chapter id="a_accessLevelPasswordReset">
    <title>Access levels and password reset page (LAM Pro)</title>

    <para>You can define different access levels for each profile to allow or
    disallow write access. The password reset page helps your deskside support
    staff to reset user passwords.</para>

    <section>
      <title id="s_accessLevel">Access levels</title>

      <para>There are three access levels:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Write access (default)</emphasis></para>

          <para>There are no restrictions. LAM admin users can manage account,
          create profiles and set passwords.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Change passwords</emphasis></para>

          <para>Similar to "Read only" except that the <link
          linkend="s_pwdReset">password reset page</link> is available.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Read only</emphasis></para>

          <para>No write access to the LDAP database is allowed. It is also
          impossible to manage account and PDF profiles.</para>

          <para>Accounts may be viewed but no changes can be saved.</para>
        </listitem>
      </itemizedlist>

      <para>The access level can be set on the server configuration
      page:</para>

      <para><screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/accessLevel.png" />
            </imageobject>
          </mediaobject>
        </screenshot></para>
    </section>

    <section id="s_pwdReset">
      <title>Password reset page</title>

      <para>This special page allows your deskside support staff to reset the
      Unix and Samba passwords of your users. If you set the <link
      linkend="s_accessLevel">access level</link> to "Change passwords" then
      LAM will not allow any changes to the LDAP database except password
      changes via this page. The account pages will be still available in
      read-only mode.</para>

      <para>You can open the password reset page by clicking on the key symbol
      on each user account:</para>

      <para><screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/passwordReset1.png" />
            </imageobject>
          </mediaobject>
        </screenshot>There are three different options to set a new
      password:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">set random password and display it on
          screen</emphasis></para>

          <para>This will set the user's password to a random value. The
          password will be 11 characters long with a random combination of
          letters, digits and ".-_".</para>

          <para>You may want to use this method to tell users their new
          passwords via phone.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">set random password and mail it to
          user</emphasis></para>

          <para>If the user account has set the mail attribute then LAM can
          send your user a mail with the new password. You can change the mail
          template to fit your needs. See the help link for further
          details.</para>

          <para>Using this method will prevent that your support staff knows
          the new password.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">set specific password</emphasis></para>

          <para>Here you can specify your own password.</para>
        </listitem>
      </itemizedlist>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/passwordReset2.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>LAM will display contact information about the user like the
      user's name, email address and telephone number. This will help your
      deskside support to easily contact your users.</para>

      <para><emphasis role="bold">Options:</emphasis></para>

      <para>Depending on the account there may be additional options
      available.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Sync Samba NT/LM password with Unix
          password:</emphasis> If a user account has Samba passwords set then
          LAM will offer to synchronize the passwords.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Unlock Samba account:</emphasis> Locked
          Samba accounts can be unlocked with the password change.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Update Samba password
          timestamps:</emphasis> This will set the timestamps when the
          password was changed (sambaPwdLastSet), may be changed again
          (sambaPwdCanChange) and must be changed again (sambaPwdMustChange).
          Only existing attributes are updated. No new attributes are
          added.</para>
        </listitem>
      </itemizedlist>

      <para></para>
    </section>
  </chapter>

  <chapter id="a_selfService">
    <title>Self service (LAM Pro)</title>

    <section>
      <title>Preparations</title>

      <section>
        <title>OpenLDAP ACLs</title>

        <para>By default only a few administrative users have write access to
        the LDAP database. Before your users may change their settings you
        must allow them to change their LDAP data.</para>

        <para>This can be done by adding an ACL to your slapd.conf which looks
        like this:</para>

        <para><emphasis role="bold">access to</emphasis></para>

        <para><emphasis role="bold">
        attrs=mail,sn,givenName,telephoneNumber,mobile,facsimileTelephoneNumber,street,postalAddress,postOfficeBox,postalCode,password</emphasis></para>

        <para><emphasis role="bold"> by self write</emphasis></para>

        <para>If you do not want them to change all attributes then reduce the
        list to fit your needs. Some modules may require additional LDAP
        attributes.</para>

        <para>Usually, the slapd.conf file is located in /etc/ldap or
        /etc/openldap.</para>
      </section>

      <section>
        <title>Other LDAP servers</title>

        <para>There exist many LDAP implementations. If you do not use
        OpenLDAP you need to write your own ACLs. Please check the manual of
        your LDAP server for instructions.</para>
      </section>
    </section>

    <section>
      <title>Creating a self service profile</title>

      <para>A self service profile defines what input fields your users see
      and some other general settings like the login caption.</para>

      <para>When you go to the LAM configuration page you will see the self
      service link at the bottom. This will lead you to the self service
      configuration pages</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/conf1.jpg" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>Now we need to create a new self service profile. Click on the
      link to manage the self service profiles.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/conf2.jpg" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>Specify a name for the new profile and enter your master
      configuration password (default is "lam") to save the profile.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/conf3.jpg" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>Now go back to the profile login and enter your master
      configuration password to edit your new profile.</para>
    </section>

    <section>
      <title>Edit your new profile</title>

      <para>On top of the page you see the link to the user login page. Copy
      this link address and give it to your users.</para>

      <para>Below the link you can specify several options.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/conf4.jpg" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <table>
        <title>General options</title>

        <tgroup cols="2">
          <tbody>
            <row>
              <entry>Server address</entry>

              <entry>The address of your LDAP server</entry>
            </row>

            <row>
              <entry>LDAP suffix</entry>

              <entry>The part of the LDAP tree where LAM should search for
              users</entry>
            </row>

            <row>
              <entry>LDAP user + password</entry>

              <entry>The DN and password which is used to search for users in
              the LDAP database. It is sufficient if this DN has only read
              rights. If you leave these fields empty LAM will try to connect
              anonymously.</entry>
            </row>

            <row>
              <entry>LDAP search attribute</entry>

              <entry>Here you can specify if your users can login with user
              name + password, email + password or other attributes.</entry>
            </row>

            <row>
              <entry>Login attribute label</entry>

              <entry>This is the description for the LDAP search attribute.
              Set it to something which your users are familiar with.</entry>
            </row>

            <row>
              <entry>Login caption</entry>

              <entry>This text is displayed at the login page. You can input
              HTML, too.</entry>
            </row>

            <row>
              <entry>Main page caption</entry>

              <entry>This text is displayed at self service main page where
              your users change their data. You can input HTML, too.</entry>
            </row>

            <row>
              <entry>Page header</entry>

              <entry>This HTML code will be placed on top of all self service
              pages. E.g. you can use this to place your custom logo. Any HTML
              code is permitted.</entry>
            </row>

            <row>
              <entry>Additional CSS links</entry>

              <entry>Here you can specify additional CSS links to change the
              layout of the self service pages. This is useful to adapt them
              to your corporate design. Please enter one link per
              line.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>On the bottom you can specify what input fields your users can
      see. It is also possible to group several input fields.</para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/conf5.jpg" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </section>

    <section>
      <title>Adapt the self service to your corporate design</title>

      <para>LAM Pro allows you to integrate customs CSS style definitions and
      design the header of all self service pages. This way you can integrate
      you own logo and use your company's colors.</para>

      <section>
        <title>Custom header</title>

        <para>The default LAM Pro header includes a logo and a horizontal
        line. You can enter any HTML code here. It will be included in the
        self services pages after the body tag.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configPageHeader.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>

      <section>
        <title>CSS files</title>

        <para>Usually, companies have regulations about their corporate design
        and use common CSS files. This assures a common appearance of all
        intranet pages (e.g. colors and fonts). To include additional CSS
        files just use the following setting for this task. The additional CSS
        links will be added after LAM Pro's default CSS link. This way you can
        overwrite LAM Pro's style.</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/configCSS.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>
    </section>
  </chapter>

  <appendix id="a_schema">
    <title>LDAP schema files</title>

    <para>Here is a list of needed LDAP schema files for the different LAM
    modules. For OpenLDAP we also provide a source where you can get the
    files.</para>

    <table frame="none" lang="" role="" tabstyle="nogrid">
      <title>LDAP schema files</title>

      <tgroup cols="6">
        <thead>
          <row>
            <entry></entry>

            <entry>Account type</entry>

            <entry>Object class(es)</entry>

            <entry>Schema name</entry>

            <entry>Source</entry>

            <entry>Notes</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_unix.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Unix accounts</entry>

            <entry>posixAccount, shadowAccount, posixGroup</entry>

            <entry>nis.schema, rfc2307bis.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>The rfc2307bis.schema is only supported by LAM Pro. Use the
            nis.schema if you do not want to upgrade to LAM Pro.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_inetOrgPerson.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Address book entries</entry>

            <entry>inetOrgPerson</entry>

            <entry>inetorgperson.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_samba.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Samba 3 accounts</entry>

            <entry>sambaSamAccount, sambaGroupMapping, sambaDomain</entry>

            <entry>samba.schema</entry>

            <entry>Part of Samba tarball (examples/LDAP/samba.schema)</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_kolab.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Kolab 2 users</entry>

            <entry>kolabUser</entry>

            <entry>kolab2.schema, rfc2739.schema</entry>

            <entry>Part of Kolab 2 installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_asterisk.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Asterisk (extension)</entry>

            <entry>AsteriskSIPUser, AsteriskExtension</entry>

            <entry>asterisk.schema</entry>

            <entry>Part of Asterisk installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_mailAlias.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Mail routing</entry>

            <entry>inetLocalMailRecipient</entry>

            <entry>misc.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_mailAlias.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Mail aliases</entry>

            <entry>nisMailAlias</entry>

            <entry>misc.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_mac.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>MAC addresses</entry>

            <entry>ieee802device</entry>

            <entry>nis.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_ipHost.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>IP addresses</entry>

            <entry>ipHost</entry>

            <entry>nis.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>This account type is only available in LAM Pro.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_user.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Simple Accounts</entry>

            <entry>account</entry>

            <entry>cosine.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_ssh.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>SSH public keys</entry>

            <entry>ldapPublicKey</entry>

            <entry>openssh-lpk.schema</entry>

            <entry>Included in patch from <ulink
            url="http://code.google.com/p/openssh-lpk/">http://code.google.com/p/openssh-lpk/</ulink></entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_groupOfNames.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Group of (unique) names</entry>

            <entry>groupOfNames, groupOfUniqueNames</entry>

            <entry>core.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>These account type is only available in LAM Pro.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_phpgroupware.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>phpGroupWare</entry>

            <entry>phpGroupwareUser, phpGroupwareGroup</entry>

            <entry>phpgroupware.schema</entry>

            <entry><ulink
            url="http://www.phpgroupware.org/">http://www.phpgroupware.org/</ulink></entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_dhcp.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>DHCP</entry>

            <entry>dhcpOptions, dhcpSubnet, dhcpServer</entry>

            <entry>dhcp.schema</entry>

            <entry>docs/schema/dhcp.schema</entry>

            <entry>The LDAP suffix should be set to your dhcpServer
            entry.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_alias.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Aliases</entry>

            <entry>alias, uidObject</entry>

            <entry>core.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>This account type is only available in LAM Pro.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_netgroup.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>NIS netgroups</entry>

            <entry>nisNetgroup</entry>

            <entry>nis.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry></entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_nisObject.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>NIS objects</entry>

            <entry>nisObject</entry>

            <entry>nis.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>This account type is only available in LAM Pro.</entry>
          </row>

          <row>
            <entry><inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/schema_ppolicy.png" />
                </imageobject>
              </inlinemediaobject></entry>

            <entry>Password policies</entry>

            <entry>pwdPolicy, device</entry>

            <entry>ppolicy.schema, core.schema</entry>

            <entry>Part of OpenLDAP installation</entry>

            <entry>This account type is only available in LAM Pro.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </appendix>

  <appendix id="a_security">
    <title>Security</title>

    <section id="a_configPasswords">
      <title>LAM configuration passwords</title>

      <para>LAM supports a two level authorization system for its
      configuration. Therefore, there are two types of configuration
      passwords:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">master configuration
          password:</emphasis> needed to change general settings,
          create/delete server profiles and self service profiles</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">server profile password:</emphasis> used
          to change the settings of a server profile (e.g. LDAP server and
          account types to manage)</para>
        </listitem>
      </itemizedlist>

      <para>The master configuration password can be used to reset a server
      profile password. Each server profile has its own profile
      password.</para>

      <para>Both password types are stored as hash values in the configuration
      files for enhanced security.</para>
    </section>

    <section>
      <title>Use of SSL</title>

      <para>The data which is transfered between you and LAM is very
      sensitive. Please always use SSL encrypted connections between LAM and
      your browser to protect yourself against network sniffers.</para>
    </section>

    <section>
      <title>LDAP with SSL and TLS</title>

      <para>SSL will be used if you use ldaps://servername in your
      configuration profile. TLS can be activated with the "Activate TLS"
      option.</para>

      <para>You will need to setup ldap.conf to trust your server certificate.
      Some installations use /etc/ldap.conf and some use /etc/ldap/ldap.conf.
      It is a good idea to symlink /etc/ldap.conf to /etc/ldap/ldap.conf.
      Specify the server CA certificate with the following option:</para>

      <para>TLS_CACERT /etc/ldap/ca/myCA/cacert.pem</para>

      <para>This needs to be the public part of the signing certificate
      authority. See "man ldap.conf" for additional options.</para>
    </section>

    <section>
      <title>Chrooted servers</title>

      <para>If your server is chrooted and you have no access to /dev/random
      or /dev/urandom this can be a security risk. LAM stores your LDAP
      password encrypted in the session. LAM uses rand() to generate the key
      if /dev/random and /dev/urandom are not accessible. Therefore the key
      can be easily guessed. An attaker needs read access to the session file
      (e.g. by another Apache instance) to exploit this.</para>
    </section>

    <section>
      <title>Protection of your LDAP password and directory contents</title>

      <para>You have to install the MCrypt extension for PHP to enable
      encryption.</para>

      <para>Your LDAP password is stored encrypted in the session file. The
      key and IV to decrypt it are stored in two cookies. We use MCrypt/AES to
      encrypt the password. All data that was read from LDAP and needs to be
      stored in the session file is also encrypted.</para>
    </section>

    <section>
      <title>Apache configuration</title>

      <para>LAM includes several .htaccess files to protect your configuration
      files and temporary data. Apache is often configured to not use
      .htaccess files by default. Therefore, please check your Apache
      configuration and change the override setting to:</para>

      <para>AllowOverride All</para>

      <para>If you are experienced in configuring Apache then you can also
      copy the security settings from the .htaccess files to your main Apache
      configuration.</para>

      <para>If possible, you should not rely on .htaccess files but also move
      the config and sess directory to a place outside of your WWW root. You
      can put a symbolic link in the LAM directory so that LAM finds the
      configuration/session files.</para>

      <para>Security sensitive directories:</para>

      <para><emphasis role="bold">config: </emphasis>Contains your LAM
      configuration and account profiles</para>

      <itemizedlist>
        <listitem>
          <para>LAM configuration passwords (SSHA hashed)</para>
        </listitem>

        <listitem>
          <para>default values for new accounts</para>
        </listitem>

        <listitem>
          <para>directory must be accessibly by Apache but needs not to be
          accessible by the browser</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">sess:</emphasis> PHP session files</para>

      <itemizedlist>
        <listitem>
          <para>LAM admin password in clear text or MCrypt encrypted</para>
        </listitem>

        <listitem>
          <para>cached LDAP entries in clear text or MCrypt encrypted</para>
        </listitem>

        <listitem>
          <para>directory must be accessibly by Apache but needs not to be
          accessible by the browser</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">tmp:</emphasis> temporary files</para>

      <itemizedlist>
        <listitem>
          <para>PDF documents which may also include passwords</para>
        </listitem>

        <listitem>
          <para>images of your users</para>
        </listitem>

        <listitem>
          <para>directory contents must be accessible by browser but directory
          itself needs not to be browseable</para>
        </listitem>
      </itemizedlist>
    </section>
  </appendix>

  <appendix>
    <title>Recommended OpenLDAP settings</title>

    <para>Some basic hints to configure the OpenLDAP server:</para>

    <para><emphasis role="bold">Size limit:</emphasis> OpenLDAP allows by
    default 500 return values per search, if you have more users/groups/hosts
    change this in slapd.conf: e.g. "sizelimit 10000" or "sizelimit -1" for
    unlimited return values.</para>

    <para><emphasis role="bold">Indices:</emphasis> Indices will improve the
    performance when searching for entries in the LDAP directory. The
    following indices are recommended:</para>

    <simplelist>
      <member>index objectClass eq</member>

      <member>index default sub</member>

      <member>index uidNumber eq</member>

      <member>index gidNumber eq</member>

      <member>index memberUid eq</member>

      <member>index cn,sn,uid,displayName pres,sub,eq</member>

      <member># Samba 3.x</member>

      <member>index sambaSID eq</member>

      <member>index sambaPrimaryGroupSID eq</member>

      <member>index sambaDomainName eq</member>
    </simplelist>
  </appendix>

  <appendix>
    <title>Setup for home directory and quota management</title>

    <para>Lamdaemon.pl is used to modify quota and home directories on a
    remote or local host via SSH. If you want wo use it you have to set up the
    following things to get it to work:</para>

    <section>
      <title>LDAP Account Manager configuration</title>

      <itemizedlist>
        <listitem>
          <para>Set the remote or local host in the configuration (e.g.
          127.0.0.1)</para>
        </listitem>

        <listitem>
          <para>Path to lamdaemon.pl, e.g.
          /srv/www/htdocs/lam/lib/lamdaemon.pl If you installed a Debian or
          RPM package then the script may be located at
          /usr/share/ldap-account-manager/lib or /var/www/html/lam/lib.</para>
        </listitem>

        <listitem>
          <para>Your LAM admin user must be a valid Unix account. It needs to
          have the object class "posixAccount" and an attribute "uid". This
          account must be accepted by the SSH daemon of your home directory
          server. Do not create a second local account but change your system
          to accept LDAP users. You can use LAM to add the Unix account part
          to your admin user.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Setup sudo</title>

      <para>The perl script has to run as root. Therefore we need a wrapper,
      sudo. Edit /etc/sudoers on host where homedirs or quotas should be used
      and add the following line:</para>

      <para>$admin All= NOPASSWD: $path_to_lamdaemon</para>

      <para><emphasis condition="">$admin</emphasis> is the admin user from
      LAM (must be a valid Unix account) and
      <emphasis>$path_to_lamdaemon</emphasis> is the path to
      lamdaemon.pl.</para>

      <para><emphasis role="bold">Example:</emphasis></para>

      <para>myAdmin ALL= NOPASSWD: /srv/www/htdocs/lam/lib/lamdaemon.pl</para>

      <para>You might need to run the sudo command once manually to init sudo.
      The command "sudo -l" will show all possible sudo commands of the
      current user.</para>
    </section>

    <section>
      <title>Setup Perl</title>

      <para>We need an extra Perl module - Quota. To install it, run:</para>

      <simplelist>
        <member>perl -MCPAN -e shell</member>

        <member>install Quota</member>
      </simplelist>

      <para>If your Perl executable is not located in /usr/bin/perl you will
      have to edit the path in the first line of lamdaemon.pl. If you have
      problems compiling the Perl modules try installing a newer release of
      your GCC compiler and the "make" application.</para>

      <para>Several Linux distributions already include a quota package for
      Perl.</para>
    </section>

    <section>
      <title>Install libssh2</title>

      <para>The libssh2 library is needed to connect to the homedir/quota
      server via SSH.</para>

      <section>
        <title>Install libssh2</title>

        <para>You can get libssh2 here: <ulink
        url="http://www.libssh2.org">http://www.libssh2.org</ulink> Unpack the
        package and install it by executing the commands "./configure", "make"
        and "make install" in the extracted directory. Several Linux
        distributions already include a package for libssh2.</para>
      </section>

      <section>
        <title>Install SSH2 for PHP</title>

        <para>Several Linux distributions already include a package (e.g.
        libssh2-php).</para>

        <para>Otherwise, run "pecl install ssh2-beta". If you have no pecl
        command then install the PHP Pear package (e.g. php-pear or php5-pear)
        for your distribution.</para>

        <para>If you want to compile it yourself, get the sources here: <ulink
        url="http://pecl.php.net/package/ssh2">http://pecl.php.net/package/ssh2</ulink></para>

        <para>After installing the PHP module please add this line to your
        php.ini:</para>

        <para>extension=ssh2.so</para>
      </section>
    </section>

    <section>
      <title>Set up SSH</title>

      <para>Your SSH daemon must offer the password authentication method. To
      activate it just use this configuration option in
      /etc/ssh/sshd_config:</para>

      <para>PasswordAuthentication yes</para>
    </section>

    <section>
      <title>Troubleshooting</title>

      <para>If you have problems managing quotas and home directories then
      these points might help:</para>

      <itemizedlist>
        <listitem>
          <para>There is a test page for lamdaemon: Login to LAM and open
          Tools -&gt; Tests -&gt; Lamdaemon test</para>
        </listitem>

        <listitem>
          <para>If you get garbage characters at the test page then PHP and
          your php5-ssh2 library may not fit together. Try recompiling the
          library and libssh2.</para>

          <para>This combination was tested successfully: libssh2 0.13 with
          php5-ssh2 0.10</para>

          <para>php5-ssh2 0.11 should have no problems with recent libssh2
          releases.</para>
        </listitem>

        <listitem>
          <para>Check /var/log/auth.log or its equivalent on your system. This
          file contains messages about all logins. If the ssh login failed
          then you will find a description about the reason here.</para>
        </listitem>

        <listitem>
          <para>Set sshd in debug mode. In /etc/ssh/sshd_conf add these
          lines:</para>

          <simplelist>
            <member>SyslogFacility AUTH</member>

            <member>LogLevel DEBUG3</member>
          </simplelist>

          <para>Now check /var/log/syslog for messages from sshd.</para>
        </listitem>

        <listitem>
          <para>Update Openssh. A Suse Linux user reported that upgrading
          Openssh solved the problem.</para>
        </listitem>
      </itemizedlist>
    </section>
  </appendix>

  <appendix>
    <title>Kolab user management</title>

    <para>Here are some notes on managing Kolab accounts with LAM:</para>

    <section>
      <title>Creating accounts</title>

      <para>The mailbox server cannot be changed after the account has been
      saved. Please make sure that the value is correct. The email address
      ("Personal" page) must match your Kolab domain, otherwise the account
      will not work.</para>
    </section>

    <section>
      <title>Deleting accounts</title>

      <para>If you want to cleanly delete accounts use the "Mark for deletion"
      button on the Kolab subpage of an account. This will also remove the
      user's mailbox. If you delete the account from the account list (which
      is standard for LAM accounts) then no cleanup actions are made.</para>
    </section>

    <section>
      <title>Managing accounts with both LAM and Kolab Admin GUI</title>

      <para>The Kolab GUI has some restrictions that LAM does not have. Please
      pay attention to the following restrictions:</para>

      <itemizedlist>
        <listitem>
          <para>Common name in LAM</para>

          <para>The common name must have the format "&lt;first name&gt;
          &lt;last name&gt;". You can leave the field empty in LAM and it will
          automatically fill in the correct value.</para>
        </listitem>

        <listitem>
          <para>Changing first/last name in Kolab GUI</para>

          <para>Do not change the first/last name of your users in the Kolab
          GUI! The GUI will change the common name which leads to an LDAP
          object class violation. This is caused by a bug in the Kolab
          GUI.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Adding a Kolab part to existing accounts</title>

      <para>If you upgrade existing non-Kolab accounts please make sure that
      the account has an Unix password.</para>
    </section>

    <section>
      <title>Installing LAM on the Kolab server</title>

      <para>You can install LAM in the directory "/kolab/var/kolab/www" which
      is the root directory for Apache. The PHP installation already includes
      all required packages.</para>
    </section>
  </appendix>

  <appendix>
    <title>InetOrgPerson and the host attribute</title>

    <para>The attribute "host" is only in objectclass account. Unfortunatly
    "account" conflicts with "inetorgperson". so there's no perfect way to use
    both.</para>

    <para>In order to get attribute host working you have to modify
    schema/inetorgperson and include host:</para>

    <literallayout># inetOrgPerson
# The inetOrgPerson represents people who are associated with an
# organization in some way.  It is a structural class and is derived
# from the organizationalPerson which is defined in X.521 [X521].
objectclass     ( 2.16.840.1.113730.3.2.2
    NAME 'inetOrgPerson'
        DESC 'RFC2798: Internet Organizational Person'
    SUP organizationalPerson
    STRUCTURAL
        MAY (
                audio $ businessCategory $ carLicense $ departmentNumber $
                displayName $ employeeNumber $ employeeType $ givenName $
                homePhone $ homePostalAddress $ initials $ jpegPhoto $
                labeledURI $ mail $ manager $ mobile $ o $ pager $
                photo $ roomNumber $ secretary $ uid $ userCertificate $
                x500uniqueIdentifier $ preferredLanguage $
                userSMIMECertificate $ userPKCS12 $ host )
        )</literallayout>
  </appendix>
</book>