diff --git a/lam/docs/manual-sources/howto.xml b/lam/docs/manual-sources/howto.xml new file mode 100644 index 00000000..42d5168c --- /dev/null +++ b/lam/docs/manual-sources/howto.xml @@ -0,0 +1,1144 @@ + + + + LDAP Account Manager - Manual + + + Overview + + 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. + + 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. + + http://www.ldap-account-manager.org/ + + Copyright (C) 2003 - 2009 + + + Michael Duergner <michael@duergner.com> + + Roland Gruber <post@rolandgruber.de> + + Tilo Lutz <tilolutz@gmx.de> + + + Requirements: + + + PHP5 (>= 5.1) + + Openldap (2.0 or greater) + + A web browser that supports CSS + + + The default password to edit the configuration options is + "lam". + + License: + + LAM is published under the GNU General Public License. The complete + list of licenses can be found in the copyright file. + + +Have fun! + The LAM development team + + + + Installation + +
+ New installation + +
+ Requirements + + LAM has the following requirements to run: + + + + Apache webserver (SSL recommended) with PHP module (PHP 5 + (>= 5.1) with ldap, gettext, xml and optional mcrypt) + + + + Some LAM plugins may require additional PHP extensions (you + will get a note on the login page if something is missing) + + + + Perl (optional, needed only for lamdaemon) + + + + OpenLDAP (>2.0) + + + + A web browser :-) + + + + MCrypt will be used to store your LDAP password encrypted in the + session file. + + See LDAP schema fles for + information about used LDAP schema files. +
+ +
+ Prepackaged releases + + LAM is available as prepackaged version for various + platforms. + +
+ Debian + + + + + + + + + + + + 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 apt-get + install ldap-account-managerto install LAM + on your server. Additionally, you may download the LAM + Debian packages from the LAM + homepage or the Debian + package homepage. + + + + +
+ +
+ Suse/Fedora + + + + + + + + + + + + + + + + There are RPM packages available on the LAM + homepage. The packages can be installed with this + commandrpm -i <path to LAM + package> + + + + +
+ +
+ Other RPM based distributions + + 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. +
+ +
+ FreeBSD + + + + + + + + + + + + LAM is part of the official FreeBSD ports tree. For + more details see these pages:FreeBSD-CVS: http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/ldap-account-managerFreshPorts: + http://www.freshports.org/sysutils/ldap-account-manager + + + + +
+
+ +
+ Installing the tar.gz + +
+ Extract the archive + + Please extract the archive with the following command: + + tar xzf ldap-account-manager-<version>.tar.gz +
+ +
+ Install the files + +
+ Manual copy + + Copy the files into the html-file scope of the web server. + For example /apache/htdocs. + + Then set the appropriate file permissions: + + + + lam/sess: write permission for apache user + + + + lam/tmp: write permission for apache user + + + + lam/config (with subdirectories): write permission for + apache user + + + + lam/lib: lamdaemon.pl must be set executable (See also + docs/readme.lamdeamon.txt) + + +
+ +
+ With configure script + + Instead of manually copying files you can also use the + included configure script to install LAM. See "./configure --help" + for a list of install options. +
+
+ +
+ Configuration files + + 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: + + + + Follow the link "LAM configuration" from the start page. + (The default passwords to edit all options is "lam") + + + + Select "Edit general settings" to setup global settings + and to change the configuration master password. + + + + 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. + + +
+
+ +
+ System configuration + +
+ PHP + + LAM runs with PHP5 (>= 5.1). Needed changes in your + php.ini: + + memory_limit = 64M +
+ +
+ Locales for non-Englisch translation + + 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. + + + Locales + + + + + Language + + Locale + + + + Catalan + + ca_ES.utf8 + + + + Chinese (Simplified) + + zh_CN.utf8 + + + + Chinese (Traditional) + + zh_TW.utf8 + + + + Czech + + cs_CZ.utf8 + + + + Dutch + + nl_NL.utf8 + + + + English + + no extra locale needed + + + + French + + fr_FR.utf8 + + + + German + + de_DE.utf8 + + + + Hungarian + + hu_HU.utf8 + + + + Italian + + it_IT.utf8 + + + + Japanese + + ja_JP.utf8 + + + + Polish + + pl_PL.utf8 + + + + Portuguese + + pt_BR.utf8 + + + + Russian + + ru_RU.utf8 + + + + Spanish + + es_ES.utf8 + + + +
+ + You can get a list of all installed locales on your system by + executing: + + locale -a + + Debian users can add locales with "dpkg-reconfigure + locales". +
+
+
+ +
+ Upgrading LAM + +
+ Migrating configuration files + + LAM stores all configuration files in the "config" folder. + Please backup the following files and copy them after the new version + is installed. + + + config/*.conf + + config/config.cfg + + config/pdf/*.xml + + config/profiles/*.xml + + + LAM Pro only: + + + config/selfService/*.* + + config/passwordMailTemplate.txt + + + Please check also the version specific instructions. They might + include additional actions. +
+ +
+ Version specific upgrade instructions + +
+ 2.2.0 -> 2.3.0 + + LAM Pro: There is now a + separate account type for group of (unique) names. Please edit your + server profiles to activate the new account type. +
+ +
+ 1.1.0 -> 2.2.0 + + No changes. +
+
+
+ + + + LDAP schema files + + 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. + + + LDAP schema files + + + + + + + Account type + + Object class(es) + + Schema name + + Source + + Notes + + + + + + + + + + + + Unix accounts + + posixAccount, shadowAccount, posixGroup + + nis.schema, rfc2307bis.schema + + Part of OpenLDAP installation + + The rfc2307bis.schema is only supported by LAM Pro. Use the + nis.schema if you do not want to upgrade to LAM Pro. + + + + + + + + + + Address book entries + + inetOrgPerson + + inetorgperson.schema + + Part of OpenLDAP installation + + + + + + + + + + + + Samba 3 accounts + + sambaSamAccount, sambaGroupMapping, sambaDomain + + samba.schema + + Part of Samba tarball (examples/LDAP/samba.schema) + + + + + + + + + + + + Kolab 2 users + + kolabUser + + kolab2.schema, rfc2739.schema + + Part of Kolab 2 installation + + + + + + + + + + + + Mail routing + + inetLocalMailRecipient + + misc.schema + + Part of OpenLDAP installation + + + + + + + + + + + + Mail aliases + + nisMailAlias + + misc.schema + + Part of OpenLDAP installation + + + + + + + + + + + + MAC addresses + + ieee802device + + nis.schema + + Part of OpenLDAP installation + + + + + + + + + + + + Simple Accounts + + account + + cosine.schema + + Part of OpenLDAP installation + + + + + + + + + + + + SSH public keys + + ldapPublicKey + + openssh-lpk.schema + + Included in patch from http://code.google.com/p/openssh-lpk/ + + + + + + + + + + + + Group of (unique) names + + groupOfNames, groupOfUniqueNames + + core.schema + + Part of OpenLDAP installation + + These modules are only available in LAM Pro. + + + + + + + + + + phpGroupWare + + phpGroupwareUser, phpGroupwareGroup + + phpgroupware.schema + + http://www.phpgroupware.org/ + + + + + + + + + + + + DHCP + + + + dhcp.schema + + docs/schema/dhcp.schema + + The LDAP suffix should be set to your dhcpServer + entry. + + + + + + + + + + Aliases + + alias, uidObject + + core.schema + + Part of OpenLDAP installation + + These modules are only available in LAM Pro. + + + +
+ + + + Security + +
+ Use of SSL + + 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. +
+ +
+ LDAP with SSL and TLS + + SSL will be used if you use ldaps://servername in your + configuration profile. TLS can be activated with the "Activate TLS" + option. + + 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: + + TLS_CACERT /etc/ldap/ca/myCA/cacert.pem + + This needs to be the public part of the signing certificate + authority. See "man ldap.conf" for additional options. +
+ +
+ Chrooted servers + + 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. +
+ +
+ Protection of your LDAP password and directory contents + + You have to install the MCrypt extension for PHP to enable + encryption. + + 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. +
+ +
+ Apache configuration + + 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: + + AllowOverride All + + If you are experienced in configuring Apache then you can also + copy the security settings from the .htaccess files to your main Apache + configuration. + + 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. + + Security sensitive directories: + + config: Contains your LAM + configuration and account profiles + + + LAM configuration passwords (SSHA hashed) + + default values for new accounts + + directory must be accessibly by Apache but needs not to be + accessible by the browser + + + sess: PHP session files + + + LAM admin password in clear text or MCrypt encrypted + + cached LDAP entries in clear text or MCrypt encrypted + + directory must be accessibly by Apache but needs not to be + accessible by the browser + + + tmp: temporary files + + + PDF documents which may also include passwords + + images of your users + + directory contents must be accessible by browser but directory + itself needs not to be browseable + +
+ + + + Recommended OpenLDAP settings + + Some basic hints to configure the OpenLDAP server: + + Size limit: 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. + + Indices: Indices will improve the + performance when searching for entries in the LDAP directory. The + following indices are recommended: + + + index objectClass eq + + index default sub + + index uidNumber eq + + index gidNumber eq + + index memberUid eq + + index cn,sn,uid,displayName pres,sub,eq + + # Samba 3.x + + index sambaSID eq + + index sambaPrimaryGroupSID eq + + index sambaDomainName eq + + + + + Setup for home directory and quota management + + 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: + +
+ LDAP Account Manager configuration + + + + Set the remote or local host in the configuration (e.g. + 127.0.0.1) + + + + 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. + + + + 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. + + +
+ +
+ Setup sudo + + 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: + + $admin All= NOPASSWD: $path + + $admin is the admin user from LAM (must be a valid Unix account) + and $path is the path to lamdaemon.pl. Example: + + myAdmin ALL= NOPASSWD: /srv/www/htdocs/lam/lib/lamdaemon.pl + + 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. +
+ +
+ Setup Perl + + We need an extra Perl module - Quota. To install it, run: + + + perl -MCPAN -e shell + + install Quota + + + 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. + + Several Linux distributions already include a quota package for + Perl. +
+ +
+ Install libssh2 + + The libssh2 library is needed to connect to the homedir/quota + server via SSH. + +
+ Install libssh2 + + You can get libssh2 here: http://www.libssh2.org 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. +
+ +
+ Install SSH2 for PHP + + Several Linux distributions already include a package (e.g. + libssh2-php). + + 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. + + If you want to compile it yourself, get the sources here: http://pecl.php.net/package/ssh2 + + After installing the PHP module please add this line to your + php.ini: + + extension=ssh2.so +
+
+ +
+ Set up SSH + + Your SSH daemon must offer the password authentication method. To + activate it just use this configuration option in + /etc/ssh/sshd_config: + + PasswordAuthentication yes +
+ +
+ Troubleshooting + + If you have problems managing quotas and home directories then + these points might help: + + + + There is a test page for lamdaemon: Login to LAM and open + Tools -> Tests -> Lamdaemon test + + + + 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. + + This combination was tested successfully: libssh2 0.13 with + php5-ssh2 0.10 + + php5-ssh2 0.11 should have no problems with recent libssh2 + releases. + + + + 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. + + + + Set sshd in debug mode. In /etc/ssh/sshd_conf add these + lines: + + + SyslogFacility AUTH + + LogLevel DEBUG3 + + + Now check /var/log/syslog for messages from sshd. + + + + Update Openssh. A Suse Linux user reported that upgrading + Openssh solved the problem. + + +
+ + + + Kolab user management + + Here are some notes on managing Kolab accounts with LAM: + +
+ Creating accounts + + 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. +
+ +
+ Deleting accounts + + 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. +
+ +
+ Managing accounts with both LAM and Kolab Admin GUI + + The Kolab GUI has some restrictions that LAM does not have. Please + pay attention to the following restrictions: + + + + Common name in LAM + + The common name must have the format "<first name> + <last name>". You can leave the field empty in LAM and it will + automatically fill in the correct value. + + + + Changing first/last name in Kolab GUI + + 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. + + +
+ +
+ Adding a Kolab part to existing accounts + + If you upgrade existing non-Kolab accounts please make sure that + the account has an Unix password. +
+ +
+ Installing LAM on the Kolab server + + 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. +
+ + + + InetOrgPerson and the host attribute + + The attribute "host" is only in objectclass account. Unfortunatly + "account" conflicts with "inetorgperson". so there's no perfect way to use + both. + + In order to get attribute host working you have to modify + schema/inetorgperson and include host: + + # 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 ) + ) + + diff --git a/lam/docs/manual-sources/make.sh b/lam/docs/manual-sources/make.sh new file mode 100755 index 00000000..f1995ddf --- /dev/null +++ b/lam/docs/manual-sources/make.sh @@ -0,0 +1,16 @@ +#!/bin/bash +# $Id$ +# +# Copyright (C) 2009 Roland Gruber +# This code is part of LDAP Account Manager (http://www.ldap-account-manager.org/) + +# This script is run to create the LAM manual. + + +rm -rf ../manual +mkdir ../manual +xsltproc -o ../manual/ --stringparam html.stylesheet.type text/css --stringparam html.stylesheet style.css /usr/share/xml/docbook/stylesheet/nwalsh/html/chunk.xsl howto.xml +mkdir ../manual/images +# cp images/*.jpg ../manual/images +cp images/*.png ../manual/images +cp style.css ../manual diff --git a/lam/docs/manual-sources/style.css b/lam/docs/manual-sources/style.css new file mode 100755 index 00000000..ada427d4 --- /dev/null +++ b/lam/docs/manual-sources/style.css @@ -0,0 +1,102 @@ +/* +$Id$ + + This code is part of LDAP Account Manager (http://www.ldap-account-manager.org/) + Copyright (C) 2009 Roland Gruber + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more detaexils. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +*/ + +/* CSS layout for LAM manual */ + + +body { + font-family:sans-serif; +} + +a { +color:#000080; +text-decoration:none; +} + +a:visited { +color:#000080; +text-decoration:none; +} + +a:hover { +color:red; +text-decoration:none; +} + +a:active { +color:red; +text-decoration:none; +} + +div.navheader table { + background-image: url(images/logo32.png); + background-repeat: no-repeat; + background-position: 10px center; +} + +div.navheader td { + font-weight:bold; + padding-left: 50px; + padding-right: 10px; +} + +div.navfooter td { + font-weight:bold; + padding-left: 10px; + padding-right: 10px; +} + +div.table table { + border-collapse:collapse; + border-width:2px; +} + +div.navheader hr { + margin-bottom:30px; +} + +div.navfooter hr { + margin-top:30px; +} + +div.mediaobject img { + margin-top:20px; + margin-bottom:20px; +} + +h1 { color:#253aa3; } +h2 { color:#000080; font-size:13pt; } + +div.nogrid table { + border-width:2px; + border-collapse:collapse; +} + +table { border-color:#253aa3; border-style:solid; } + +div.noborder table { + border-width:0px; + border-collapse:collapse; + border-style:none; + border-color:transparent; +} +