[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en: ldap-howto.xml

[Sven Vermeulen (swift)]

swift       11/08/15 20:25:30

  Modified:             ldap-howto.xml
  Log:
  Fix #176075 - Updated OpenLDAP guide

Revision  Changes    Path
1.44                 xml/htdocs/doc/en/ldap-howto.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/ldap-howto.xml?rev=1.44&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/ldap-howto.xml?rev=1.44&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/ldap-howto.xml?r1=1.43&r2=1.44

Index: ldap-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -r1.43 -r1.44
--- ldap-howto.xml	18 Apr 2011 02:01:11 -0000	1.43
+++ ldap-howto.xml	15 Aug 2011 20:25:30 -0000	1.44
@@ -1,15 +1,15 @@
 <?xml version='1.0' encoding='UTF-8'?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v 1.43 2011/04/18 02:01:11 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v 1.44 2011/08/15 20:25:30 swift Exp $ -->
 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
 
-<guide disclaimer="draft">
+<guide>
 <title>Gentoo Guide to OpenLDAP Authentication</title>
 
 <author title="Author">
   <mail link="sj7trunks@××××××××.net">Benjamin Coles</mail>
 </author>
-<author title="Editor">
-  <mail link="swift@g.o">Sven Vermeulen</mail>
+<author title="Author">
+  <mail link="swift"/>
 </author>
 <author title="Editor">
   <mail link="tseng@g.o">Brandon Hale</mail>
@@ -33,8 +33,8 @@
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 <license/>
 
-<version>5</version>
-<date>2011-04-17</date>
+<version>6</version>
+<date>2011-08-15</date>
 
 <chapter>
 <title>Getting Started with OpenLDAP</title>
@@ -166,52 +166,66 @@
 
 <pre caption="Generate password">
 # <i>slappasswd</i>
-New password: my-password
-Re-enter new password: my-password
+New password: <i>my-password</i>
+Re-enter new password: <i>my-password</i>
 {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
 </pre>
 
 <p>
-Now edit the LDAP Server config at <path>/etc/openldap/slapd.conf</path>:
+Now edit the LDAP Server config at <path>/etc/openldap/slapd.conf</path>. Below
+we'll give a sample configuration file to get things started. For a more
+detailed analysis of the configuration file, we suggest that you work through
+the OpenLDAP Administrator's Guide.
 </p>
 
 <pre caption="/etc/openldap/slapd.conf">
-<comment># Include the needed data schemes below core.schema</comment>
-include         /etc/openldap/schema/cosine.schema
-include         /etc/openldap/schema/inetorgperson.schema
-include         /etc/openldap/schema/nis.schema
-
-<comment>Uncomment modulepath and hdb module</comment>
-# Load dynamic backend modules:
-modulepath    /usr/lib/openldap/openldap
-# moduleload    back_shell.so
-# moduleload    back_relay.so
-# moduleload    back_perl.so
-# moduleload    back_passwd.so
-# moduleload    back_null.so
-# moduleload    back_monitor.so
-# moduleload    back_meta.so
-moduleload    back_hdb.so
-# moduleload    back_dnssrv.so
+include	/etc/openldap/schema/core.schema
+include /etc/openldap/schema/cosine.schema
+include /etc/openldap/schema/inetorgperson.schema
+include /etc/openldap/schema/nis.schema
+include	/etc/openldap/schema/misc.schema
+
+pidfile /var/run/openldap/slapd.pid
+argsfile /var/run/openldap/slapd.args
 
-<comment># Uncomment sample access restrictions (Note: maintain indentation!)</comment>
+serverID 0 <comment>Used in case of replication</comment>
+loglevel 0
+
+<comment>## Access Controls</comment>
 access to dn.base="" by * read
 access to dn.base="cn=Subschema" by * read
 access to *
-   by self write
-   by users read
-   by anonymous auth
+  by self write
+  by users read
+  by anonymous read
 
+<comment>## Database definition</comment>
+database hdb
+suffix "dc=genfic,dc=com"
+checkpoint 32 30
+rootdn "cn=Manager,dc=genfic,dc=com"
+rootpw "{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4" <comment># See earlier slappasswd command</comment>
+directory "/var/lib/openldap-ldbm"
+index objectClass eq
+
+<comment>## Synchronisation (pull from other LDAP server)</comment>
+syncrepl rid=000
+  provider=ldap://ldap2.genfic.com
+  type=refreshAndPersist
+  retry="5 5 300 +"
+  searchbase="dc=genfic,dc=com"
+  attrs="*,+"
+  bindmethod="simple"
+  binddn="cn=ldapreader,dc=genfic,dc=com"
+  credentials="ldapsyncpass"
 
-<comment># BDB Database definition</comment>
+index entryCSN eq
+index entryUUID eq
 
-database        hdb
-suffix          "dc=genfic,dc=com"
-checkpoint      32      30 # &lt;kbyte&gt; &lt;min&gt;
-rootdn          "cn=Manager,dc=genfic,dc=com"
-rootpw          <i>{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4</i>
-directory       /var/lib/openldap-ldbm
-index           objectClass     eq
+mirrormode TRUE
+
+overlay syncprov
+syncprov-checkpoint 100 10
 </pre>
 
 <p>
@@ -223,17 +237,27 @@
 <comment>(Add the following...)</comment>
 
 BASE         dc=genfic, dc=com
-URI          ldap://auth.genfic.com:389/
+URI          ldap://ldap.genfic.com:389/ ldap://ldap1.genfic.com:389/ ldap://ldap2.genfic.com:389/
 TLS_REQCERT  allow
+TIMELIMIT    2
 </pre>
 
 <p>
-Now edit <path>/etc/conf.d/slapd</path> and uncomment the following OPTS line:
+Now edit <path>/etc/conf.d/slapd</path> and set the following OPTS line:
 </p>
 
 <pre caption="/etc/conf.d/slapd">
-<comment># Note: we don't use cn=config here, so stay with this line:</comment>
-OPTS="-F /etc/openldap/slapd.d -h 'ldaps:// ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
+OPTS="-h 'ldaps:// ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
+</pre>
+
+<p>
+Finally, create the <path>/var/lib/openldap-ldbm</path> structure:
+</p>
+
+<pre caption="Preparing the openldap-ldbm location">
+~# <i>mkdir -p /var/lib/openldap-ldbm</i>
+~# <i>chown ldap:ldap /var/lib/openldap-ldbm</i>
+~# <i>chmod 700 /var/lib/openldap-ldbm</i>
 </pre>
 
 <p>
@@ -262,18 +286,153 @@
 </chapter>
 
 <chapter>
+<title>Replication</title>
+<section>
+<title>If you need high availability</title>
+<body>
+
+<p>
+If your environment requires high availability, then you need to setup
+replication of changes across multiple LDAP systems. Replication within OpenLDAP
+is, in this guide, set up using a specific replication account
+(<c>ldapreader</c>) which has read rights on the primary LDAP server and which
+pulls in changes from the primary LDAP server to the secundary.
+</p>
+
+<p>
+This setup is then mirrored, allowing the secundary LDAP server to act as a
+primary. Thanks to OpenLDAP's internal structure, changes are not re-applied if
+they are already in the LDAP structure.
+</p>
+
+</body>
+</section>
+<section>
+<title>Setting Up Replication</title>
+<body>
+
+<p>
+To setup replication, first setup a second OpenLDAP server, similarly as above.
+However take care that, in the configuration file, 
+</p>
+
+<ul>
+  <li>
+    the <e>sync replication provider</e> is pointing to the <e>other</e> system
+  </li>
+  <li>
+    the <e>serverID</e> of each OpenLDAP system is different
+  </li>
+</ul>
+
+<p>
+Next, create the synchronisation account. We will create an LDIF file (the
+format used as data input for LDAP servers) and add it to each LDAP server:
+</p>
+
+<pre caption="Creating the ldapreader account">
+~# <i>slappasswd -s myreaderpassword</i>
+ {SSHA}XvbdAv6rdskp9HgFaFL9YhGkJH3HSkiM
+
+~# <i>cat ldapreader.ldif</i>
+dn: cn=ldapreader,dc=genfic,dc=com
+userPassword: {SSHA}XvbdAv6rdskp9HgFaFL9YhGkJH3HSkiM
+objectClass: organizationalRole
+objectClass: simpleSecurityObject
+cn: ldapreader
+description: LDAP reader used for synchronization
+
+~# <i>ldapadd -x -W -D "cn=Manager,dc=genfic,dc=com" -f ldapreader.ldif</i>
+Password: <comment>enter the administrative password</comment>
+</pre>
+
+</body>
+</section>
+</chapter>
+
+<chapter>
 <title>Client Configuration</title>
 <section>
 <title>Migrate existing data to ldap</title>
 <body>
 
 <p>
+Configuring OpenLDAP for centralized administration and management of common
+Linux/Unix items isn't easy, but thanks to some tools and scripts available on
+the Internet, migrating a system from a single-system administrative
+point-of-view towards an OpenLDAP-based, centralized managed system isn't hard
+either.
+</p>
+
+<p>
 Go to <uri
 link="http://www.padl.com/OSS/MigrationTools.html">http://www.padl.com/OSS/MigrationTools.html</uri>
-and fetch the scripts there. Configuration is stated on the page. We don't ship
-this anymore because the scripts are a potential security hole if you leave
-them on the system after porting. When you've finished migrating your data,
-continue to the next section.
+and fetch the scripts there. You'll need the migration tools and the
+<c>make_master.sh</c> script.
+</p>
+
+<p>
+Next, extract the tools and copy the <c>make_master.sh</c> script inside the
+extracted location:
+</p>
+
+<pre caption="Extracting the MigrationTools">
+~# <i>mktemp -d</i>
+/tmp/tmp.zchomocO3Q
+~# <i>cd /tmp/tmp.zchomocO3Q</i>
+~# <i>tar xvzf /path/to/MigrationTools.tgz</i>
+~# <i>mv /path/to/make_master.sh MigrationTools-47</i>
+~# <i>cd MigrationTools-47</i>
+</pre>
+
+<p>
+The next step now is to migrate the information of your system to OpenLDAP. The
+<c>make_master.sh</c> script will do this for you, after you have provided it
+with the information regarding your LDAP structure and environment.
+</p>
+
+<p>
+At the time of writing, the tools require the following input:
+</p>
+
+<table>
+<tr>
+  <th>Input</th>
+  <th>Description</th>
+  <th>Example</th>
+</tr>
+<tr>
+  <ti>LDAP BaseDN</ti>
+  <ti>The base location (root) of your tree</ti>
+  <ti>dc=genfic,dc=com</ti>
+</tr>
+<tr>
+  <ti>Mail domain</ti>
+  <ti>Domain used in e-mail addresses</ti>
+  <ti>genfic.com</ti>
+</tr>
+<tr>
+  <ti>Mail host</ti>
+  <ti>FQDN of your mail server infrastructure</ti>
+  <ti>smtp.genfic.com</ti>
+</tr>
+<tr>
+  <ti>LDAP Root DN</ti>
+  <ti>Administrative account information for your LDAP structure</ti>
+  <ti>cn=Manager,dc=genfic,dc=com</ti>
+</tr>
+<tr>
+  <ti>LDAP Root Password</ti>
+  <ti>
+    Password for the administrative account, cfr earlier <c>slappasswd</c>
+    command
+  </ti>
+  <ti></ti>
+</tr>
+</table>
+
+<p>
+The tool will also ask you which accounts and settings you want to migrate.
 </p>
 
 </body>
@@ -310,7 +469,7 @@
 #%PAM-1.0
 
 auth       required     pam_env.so
-auth       sufficient   pam_unix.so try_first_pass likeauth nullok
+auth       <i>sufficient</i>   pam_unix.so try_first_pass likeauth nullok
 <i>auth       sufficient   pam_ldap.so use_first_pass</i>
 auth       required     pam_deny.so
 
@@ -318,7 +477,7 @@
 account    required     pam_unix.so
 
 password   required     pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 try_first_pass retry=3
-password   sufficient   pam_unix.so try_first_pass use_authtok nullok md5 shadow
+password   <i>sufficient</i>   pam_unix.so try_first_pass use_authtok nullok md5 shadow
 <i>password   sufficient   pam_ldap.so use_authtok use_first_pass</i>
 password   required     pam_deny.so
 
@@ -338,20 +497,20 @@
 
 suffix          "dc=genfic,dc=com"
 <comment>#rootbinddn uid=root,ou=People,dc=genfic,dc=com</comment>
-
-uri ldap://auth.genfic.com/
-pam_password exop
-
+bind_policy soft
+bind_timelimit 2
 ldap_version 3
+nss_base_group ou=Group,dc=genfic,dc=com
+nss_base_hosts ou=Hosts,dc=genfic,dc=com
+nss_base_passwd ou=People,dc=genfic,dc=com
+nss_base_shadow ou=People,dc=genfic,dc=com
 pam_filter objectclass=posixAccount
 pam_login_attribute uid
 pam_member_attribute memberuid
-nss_base_passwd ou=People,dc=genfic,dc=com
-nss_base_shadow ou=People,dc=genfic,dc=com
-nss_base_group  ou=Group,dc=genfic,dc=com
-nss_base_hosts  ou=Hosts,dc=genfic,dc=com
-
+pam_password exop
 scope one
+timelimit 2
+uri ldap://ldap.genfic.com/ ldap://ldap1.genfic.com ldap://ldap2.genfic.com
 </pre>
 
 <p>
@@ -376,26 +535,14 @@
 </pre>
 
 <p>
-To test the changes, type:
-</p>
-
-<pre caption="Testing LDAP Auth">
-# <i>getent passwd|grep 0:0</i>
-
-<comment>(You should get two entries back:)</comment>
-root:x:0:0:root:/root:/bin/bash
-root:x:0:0:root:/root:/bin/bash
-</pre>
-
-<p>
 If you noticed one of the lines you pasted into your <path>/etc/ldap.conf</path>
 was commented out (the <c>rootbinddn</c> line): you don't need it unless you
 want to change a user's password as superuser. In this case you need to echo
 the root password to <path>/etc/ldap.secret</path> in plaintext. This is
-<brite>DANGEROUS</brite> and should be chmoded to 600. What I do is keep that
-file blank and when I need to change someones password thats both in the ldap
-and <path>/etc/passwd</path> I put the pass in there for 10 seconds while I
-change it and remove it when I'm done.
+<brite>DANGEROUS</brite> and should be chmoded to 600. What you might want to
+do is keep that file blank and when you need to change someones password thats
+both in the ldap and <path>/etc/passwd</path>, put the pass in there for 10
+seconds while changing the users password and remove it when done.
 </p>
 
 </body>