doc/en/ldap-howto.xml

<?xml version='1.0' encoding='UTF-8'?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v 1.42 2010/07/13 19:40:28 nightmorph Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide disclaimer="draft">
<title>Gentoo Guide to OpenLDAP Authentication</title>

<author title="Author">
  <mail link="sj7trunks@pendulus.net">Benjamin Coles</mail>
</author>
<author title="Editor">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
  <mail link="tseng@gentoo.org">Brandon Hale</mail>
</author>
<author title="Editor">
  <mail link="bennyc@gentoo.org">Benny Chuang</mail>
</author>
<author title="Editor">
  <mail link="jokey"/>
</author>
<author title="Editor">
  <mail link="nightmorph"/>
</author>

<abstract>
This guide introduces the basics of LDAP and shows you how to setup
OpenLDAP for authentication purposes between a group of Gentoo boxes.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>5</version>
<date>2011-04-17</date>

<chapter>
<title>Getting Started with OpenLDAP</title>
<section>
<title>What is LDAP?</title>
<body>

<p>
LDAP stands for <e>Lightweight Directory Access Protocol</e>. Based on
X.500 it encompasses most of its primary functions, but lacks the more
esoteric functions that X.500 has. Now what is this X.500 and why is there an
LDAP?
</p>

<p>
X.500 is a model for Directory Services in the OSI concept. It contains
namespace definitions and the protocols for querying and updating the
directory. However, X.500 has been found to be overkill in many situations.
Enter LDAP. Like X.500 it provides a data/namespace model for the
directory and a protocol too. However, LDAP is designed to run directly
over the TCP/IP stack. See LDAP as a slim-down version of X.500.
</p>

</body>
</section>

<section>
<title>I don't get it. What is a directory?</title>
<body>

<p>
A directory is a specialized database designed for frequent queries but
infrequent updates. Unlike general databases they don't contain
transaction support or roll-back functionality. Directories are easily
replicated to increase availability and reliability. When directories
are replicated, temporary inconsistencies are allowed as long as they
get synchronised eventually.
</p>

</body>
</section>

<section>
<title>How is information structured?</title>
<body>

<p>
All information inside a directory is structured hierarchically. Even
more, if you want to enter data inside a directory, the directory must
know how to store this data inside a tree. Lets take a look at a
fictional company and an Internet-like tree:
</p>

<pre caption = "Organisational structure for GenFic, a Fictional Gentoo company">
dc:         com
             |
dc:        genfic         <comment>(Organisation)</comment>
          /      \
ou:   People   servers    <comment>(Organisational Units)</comment>
      /    \     ..
uid: ..   John            <comment>(OU-specific data)</comment>
</pre>

<p>
Since you don't feed data to the database in this ascii-art like manner,
every node of such a tree must be defined. To name such nodes, LDAP uses
a naming scheme. Most LDAP distributions (including OpenLDAP) already
contain quite a number of predefined (and general approved) schemes,
such as the inetorgperson, a frequently used scheme to define users.
</p>

<p>
Interested users are encouraged to read the <uri
link="http://www.openldap.org/doc/admin24/">OpenLDAP Admin Guide</uri>.
</p>

</body>
</section>
<section>
<title>So... What's the Use?</title>
<body>

<p>
LDAP can be used for various things. This document focuses on centralised user
management, keeping all user accounts in a single LDAP location (which doesn't
mean that it's housed on a single server, LDAP supports high availability and
redundancy), yet other goals can be achieved using LDAP as well.
</p>

<ul>
  <li>Public Key Infrastructure</li>
  <li>Shared Calendar</li>
  <li>Shared Addressbook</li>
  <li>Storage for DHCP, DNS, ...</li>
  <li>
    System Class Configuration Directives (keeping track of several server
    configurations)
  </li>
  <li>...</li>
</ul>

</body>
</section>
</chapter>

<chapter>
<title>Configuring OpenLDAP</title>
<section>
<title>Initial Configuration</title>
<body>

<note>
In this document we use the genfic.com address as an example. You will
ofcourse have to change this. However, make sure that the top node is an
official top level domain (net, com, cc, be, ...).
</note>

<p>
Let's first emerge OpenLDAP:
</p>

<pre caption="Install OpenLDAP">
# <i>emerge openldap</i>
</pre>

<p>
Now generate an encrypted password we'll use later on:
</p>

<pre caption="Generate password">
# <i>slappasswd</i>
New password: my-password
Re-enter new password: my-password
{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
</pre>

<p>
Now edit the LDAP Server config at <path>/etc/openldap/slapd.conf</path>:
</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

<comment># Uncomment sample access restrictions (Note: maintain indentation!)</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


<comment># BDB Database definition</comment>

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
</pre>

<p>
Next we edit the LDAP Client configuration file:
</p>

<pre caption="/etc/openldap/ldap.conf">
# <i>nano -w /etc/openldap/ldap.conf</i>
<comment>(Add the following...)</comment>

BASE         dc=genfic, dc=com
URI          ldap://auth.genfic.com:389/
TLS_REQCERT  allow
</pre>

<p>
Now edit <path>/etc/conf.d/slapd</path> and uncomment 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'"
</pre>

<p>
Start slapd:
</p>

<pre caption = "Starting SLAPd">
# <i>/etc/init.d/slapd start</i>
</pre>

<p>
You can test with the following command:
</p>

<pre caption = "Test the SLAPd daemon">
# <i>ldapsearch -x -D "cn=Manager,dc=genfic,dc=com" -W</i>
</pre>

<p>
If you receive an error, try adding <c>-d 255</c> to increase the
verbosity and solve the issue you have.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Client Configuration</title>
<section>
<title>Migrate existing data to ldap</title>
<body>

<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.
</p>

</body>
</section>
<section>
<title>Configuring PAM</title>
<body>

<p>
First, we will configure PAM to allow LDAP authorization. Install
<c>sys-auth/pam_ldap</c> so that PAM supports LDAP authorization, and
<c>sys-auth/nss_ldap</c> so that your system can cope with LDAP servers for
additional information (used by <path>nsswitch.conf</path>).
</p>

<pre caption="Installing pam_ldap and nss_ldap">
# <i>emerge pam_ldap nss_ldap</i>
</pre>

<p>
Now add the following lines in the right places to
<path>/etc/pam.d/system-auth</path>:
</p>

<pre caption="/etc/pam.d/system-auth">
<comment># Note: only add them. Don't kill stuff already in there or your box won't let you login again!</comment>

auth       sufficient   pam_ldap.so use_first_pass
account    sufficient   pam_ldap.so
password   sufficient   pam_ldap.so use_authtok use_first_pass
session    optional     pam_ldap.so

<comment># Example file:</comment>
#%PAM-1.0

auth       required     pam_env.so
auth       sufficient   pam_unix.so try_first_pass likeauth nullok
<i>auth       sufficient   pam_ldap.so use_first_pass</i>
auth       required     pam_deny.so

<i>account    sufficient   pam_ldap.so</i>
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
<i>password   sufficient   pam_ldap.so use_authtok use_first_pass</i>
password   required     pam_deny.so

session    required     pam_limits.so
session    required     pam_unix.so
<i>session    optional     pam_ldap.so</i>

</pre>

<p>
Now change <path>/etc/ldap.conf</path> to read:
</p>

<pre caption="/etc/ldap.conf">
<comment>#host 127.0.0.1</comment>
<comment>#base dc=padl,dc=com</comment>

suffix          "dc=genfic,dc=com"
<comment>#rootbinddn uid=root,ou=People,dc=genfic,dc=com</comment>

uri ldap://auth.genfic.com/
pam_password exop

ldap_version 3
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

scope one
</pre>

<p>
Next, copy over the (OpenLDAP) <path>ldap.conf</path> file from the server to
the client so the clients are aware of the LDAP environment:
</p>

<pre caption="Copying over the OpenLDAP ldap.conf">
<comment>(Substitute ldap-server with your LDAP server name)</comment>
# <i>scp ldap-server:/etc/openldap/ldap.conf /etc/openldap</i>
</pre>

<p>
Finally, configure your clients so that they check the LDAP for system
accounts:
</p>

<pre caption="/etc/nsswitch.conf">
passwd:         files ldap
group:          files ldap
shadow:         files ldap
</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.
</p>

</body>
</section>
</chapter>

<chapter>
<title>LDAP Server Security Settings</title>
<section>
<title>OpenLDAP permissions</title>
<body>

<p>
If we take a look at <path>/etc/openldap/slapd.conf</path> you'll see
that you can specify the ACLs (permissions if you like) of what data
users can read and/or write:
</p>

<pre caption="/etc/openldap/slapd.conf">
access to *
  by dn="uid=root,ou=People,dc=genfic,dc=com" write
  by users read
  by anonymous auth

access to attrs=userPassword,gecos,description,loginShell
  by self write
</pre>

<p>
This gives you access to everything a user should be able to change. If it's
your information, then you got write access to it; if it's another user their
information then you can read it; anonymous people can send a login/pass to get
logged in. There are four levels, ranking them from lowest to greatest: <c>auth
search read write</c>.
</p>

<p>
The next ACL is a bit more secure as it blocks normal users to read
other people their shadowed password:
</p>

<pre caption="/etc/openldap/slapd.conf">
access to attrs="userPassword"
  by dn="uid=root,ou=People,dc=genfic,dc=com" write
  by dn="uid=John,ou=People,dc=genfic,dc=com" write
  by anonymous auth
  by self write
  by * none

access to *
  by dn="uid=root,ou=People,dc=genfic,dc=com" write
  by dn="uid=John,ou=People,dc=genfic,dc=com" write
  by * search
</pre>

<p>
This example gives root and John access to read/write/search
for everything in the the tree below <path>dc=genfic,dc=com</path>. This also
lets users change their own <path>userPassword</path>'s. As for the ending
statement everyone else just has a search ability meaning they can fill in a
search filter, but can't read the search results. Now you can have multiple
acls but the rule of the thumb is it processes from bottom up, so your
toplevel should be the most restrictive ones.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Working with OpenLDAP</title>
<section>
<title>Maintaining the directory</title>
<body>

<p>
You can start using the directory to authenticate users in
apache/proftpd/qmail/samba. You can manage it with phpldapadmin, diradm,
jxplorer, or lat, which provide easy management interfaces.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Acknowledgements</title>
<section>
<body>

<p>
We would like to thank Matt Heler for lending us his box for the purpose of
this guide. Thanks also go to the cool guys in #ldap @ irc.freenode.net
</p>

</body>
</section>
</chapter>
</guide>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2	nightmorph	1.43	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v 1.42 2010/07/13 19:40:28 nightmorph Exp $ -->
3	swift	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5	nightmorph	1.40	<guide disclaimer="draft">
6	bennyc	1.5	<title>Gentoo Guide to OpenLDAP Authentication</title>
7	swift	1.1
8			<author title="Author">
9	swift	1.26	<mail link="sj7trunks@pendulus.net">Benjamin Coles</mail>
10	swift	1.1	</author>
11			<author title="Editor">
12	nightmorph	1.35	<mail link="swift@gentoo.org">Sven Vermeulen</mail>
13	swift	1.1	</author>
14			<author title="Editor">
15			<mail link="tseng@gentoo.org">Brandon Hale</mail>
16			</author>
17	bennyc	1.5	<author title="Editor">
18			<mail link="bennyc@gentoo.org">Benny Chuang</mail>
19			</author>
20	nightmorph	1.36	<author title="Editor">
21			<mail link="jokey"/>
22			</author>
23	nightmorph	1.40	<author title="Editor">
24			<mail link="nightmorph"/>
25			</author>
26	swift	1.1
27			<abstract>
28			This guide introduces the basics of LDAP and shows you how to setup
29	bennyc	1.5	OpenLDAP for authentication purposes between a group of Gentoo boxes.
30	swift	1.1	</abstract>
31
32	swift	1.27	<!-- The content of this document is licensed under the CC-BY-SA license -->
33			<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
34	swift	1.10	<license/>
35
36	nightmorph	1.43	<version>5</version>
37			<date>2011-04-17</date>
38	swift	1.1
39			<chapter>
40			<title>Getting Started with OpenLDAP</title>
41			<section>
42			<title>What is LDAP?</title>
43			<body>
44
45			<p>
46			LDAP stands for <e>Lightweight Directory Access Protocol</e>. Based on
47			X.500 it encompasses most of its primary functions, but lacks the more
48			esoteric functions that X.500 has. Now what is this X.500 and why is there an
49			LDAP?
50			</p>
51
52			<p>
53			X.500 is a model for Directory Services in the OSI concept. It contains
54			namespace definitions and the protocols for querying and updating the
55			directory. However, X.500 has been found to be overkill in many situations.
56			Enter LDAP. Like X.500 it provides a data/namespace model for the
57			directory and a protocol too. However, LDAP is designed to run directly
58			over the TCP/IP stack. See LDAP as a slim-down version of X.500.
59			</p>
60
61			</body>
62			</section>
63
64			<section>
65			<title>I don't get it. What is a directory?</title>
66			<body>
67
68			<p>
69			A directory is a specialized database designed for frequent queries but
70			infrequent updates. Unlike general databases they don't contain
71			transaction support or roll-back functionality. Directories are easily
72			replicated to increase availability and reliability. When directories
73			are replicated, temporary inconsistencies are allowed as long as they
74	swift	1.37	get synchronised eventually.
75	swift	1.1	</p>
76
77			</body>
78			</section>
79
80			<section>
81			<title>How is information structured?</title>
82			<body>
83
84			<p>
85			All information inside a directory is structured hierarchically. Even
86			more, if you want to enter data inside a directory, the directory must
87			know how to store this data inside a tree. Lets take a look at a
88			fictional company and an Internet-like tree:
89			</p>
90
91			<pre caption = "Organisational structure for GenFic, a Fictional Gentoo company">
92			dc: com
93			\|
94			dc: genfic <comment>(Organisation)</comment>
95			/ \
96	nightmorph	1.40	ou: People servers <comment>(Organisational Units)</comment>
97	swift	1.37	/ \ ..
98	nightmorph	1.40	uid: .. John <comment>(OU-specific data)</comment>
99	swift	1.1	</pre>
100
101			<p>
102			Since you don't feed data to the database in this ascii-art like manner,
103			every node of such a tree must be defined. To name such nodes, LDAP uses
104			a naming scheme. Most LDAP distributions (including OpenLDAP) already
105			contain quite a number of predefined (and general approved) schemes,
106			such as the inetorgperson, a frequently used scheme to define users.
107			</p>
108
109			<p>
110			Interested users are encouraged to read the <uri
111	nightmorph	1.41	link="http://www.openldap.org/doc/admin24/">OpenLDAP Admin Guide</uri>.
112	swift	1.1	</p>
113
114			</body>
115			</section>
116	swift	1.21	<section>
117			<title>So... What's the Use?</title>
118			<body>
119
120			<p>
121			LDAP can be used for various things. This document focuses on centralised user
122			management, keeping all user accounts in a single LDAP location (which doesn't
123			mean that it's housed on a single server, LDAP supports high availability and
124			redundancy), yet other goals can be achieved using LDAP as well.
125			</p>
126
127			<ul>
128			<li>Public Key Infrastructure</li>
129			<li>Shared Calendar</li>
130			<li>Shared Addressbook</li>
131			<li>Storage for DHCP, DNS, ...</li>
132			<li>
133			System Class Configuration Directives (keeping track of several server
134			configurations)
135			</li>
136			<li>...</li>
137			</ul>
138	swift	1.1
139	swift	1.21	</body>
140			</section>
141	swift	1.1	</chapter>
142
143			<chapter>
144			<title>Configuring OpenLDAP</title>
145			<section>
146			<title>Initial Configuration</title>
147			<body>
148
149			<note>
150			In this document we use the genfic.com address as an example. You will
151			ofcourse have to change this. However, make sure that the top node is an
152			official top level domain (net, com, cc, be, ...).
153			</note>
154
155			<p>
156	nightmorph	1.39	Let's first emerge OpenLDAP:
157	swift	1.1	</p>
158
159			<pre caption="Install OpenLDAP">
160	nightmorph	1.39	# <i>emerge openldap</i>
161	swift	1.1	</pre>
162
163			<p>
164	nightmorph	1.36	Now generate an encrypted password we'll use later on:
165			</p>
166
167			<pre caption="Generate password">
168	nightmorph	1.39	# <i>slappasswd</i>
169	nightmorph	1.36	New password: my-password
170			Re-enter new password: my-password
171			{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
172			</pre>
173
174			<p>
175			Now edit the LDAP Server config at <path>/etc/openldap/slapd.conf</path>:
176	swift	1.1	</p>
177
178			<pre caption="/etc/openldap/slapd.conf">
179	nightmorph	1.36	<comment># Include the needed data schemes below core.schema</comment>
180	swift	1.1	include /etc/openldap/schema/cosine.schema
181			include /etc/openldap/schema/inetorgperson.schema
182			include /etc/openldap/schema/nis.schema
183
184	nightmorph	1.36	<comment>Uncomment modulepath and hdb module</comment>
185			# Load dynamic backend modules:
186			modulepath /usr/lib/openldap/openldap
187			# moduleload back_shell.so
188			# moduleload back_relay.so
189			# moduleload back_perl.so
190			# moduleload back_passwd.so
191			# moduleload back_null.so
192			# moduleload back_monitor.so
193			# moduleload back_meta.so
194			moduleload back_hdb.so
195			# moduleload back_dnssrv.so
196
197			<comment># Uncomment sample access restrictions (Note: maintain indentation!)</comment>
198			access to dn.base="" by * read
199			access to dn.base="cn=Subschema" by * read
200			access to *
201			by self write
202			by users read
203			by anonymous auth
204	swift	1.1
205
206	nightmorph	1.36	<comment># BDB Database definition</comment>
207	swift	1.1
208	nightmorph	1.36	database hdb
209	swift	1.1	suffix "dc=genfic,dc=com"
210	nightmorph	1.36	checkpoint 32 30 # <kbyte> <min>
211	swift	1.1	rootdn "cn=Manager,dc=genfic,dc=com"
212	nightmorph	1.36	rootpw <i>{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4</i>
213	swift	1.1	directory /var/lib/openldap-ldbm
214			index objectClass eq
215			</pre>
216
217			<p>
218	nightmorph	1.36	Next we edit the LDAP Client configuration file:
219	swift	1.1	</p>
220
221			<pre caption="/etc/openldap/ldap.conf">
222			# <i>nano -w /etc/openldap/ldap.conf</i>
223	neysx	1.23	<comment>(Add the following...)</comment>
224	swift	1.1
225	swift	1.6	BASE dc=genfic, dc=com
226	nightmorph	1.36	URI ldap://auth.genfic.com:389/
227	swift	1.6	TLS_REQCERT allow
228	swift	1.1	</pre>
229
230			<p>
231	nightmorph	1.42	Now edit <path>/etc/conf.d/slapd</path> and uncomment the following OPTS line:
232	swift	1.1	</p>
233
234			<pre caption="/etc/conf.d/slapd">
235	nightmorph	1.36	<comment># Note: we don't use cn=config here, so stay with this line:</comment>
236	nightmorph	1.42	OPTS="-F /etc/openldap/slapd.d -h 'ldaps:// ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
237	swift	1.1	</pre>
238
239			<p>
240			Start slapd:
241			</p>
242
243			<pre caption = "Starting SLAPd">
244			# <i>/etc/init.d/slapd start</i>
245			</pre>
246
247			<p>
248			You can test with the following command:
249			</p>
250
251			<pre caption = "Test the SLAPd daemon">
252	nightmorph	1.38	# <i>ldapsearch -x -D "cn=Manager,dc=genfic,dc=com" -W</i>
253	swift	1.1	</pre>
254
255			<p>
256			If you receive an error, try adding <c>-d 255</c> to increase the
257			verbosity and solve the issue you have.
258			</p>
259
260			</body>
261			</section>
262			</chapter>
263
264			<chapter>
265	nightmorph	1.36	<title>Client Configuration</title>
266	swift	1.1	<section>
267	nightmorph	1.36	<title>Migrate existing data to ldap</title>
268	swift	1.1	<body>
269
270			<p>
271	nightmorph	1.36	Go to <uri
272			link="http://www.padl.com/OSS/MigrationTools.html">http://www.padl.com/OSS/MigrationTools.html</uri>
273			and fetch the scripts there. Configuration is stated on the page. We don't ship
274			this anymore because the scripts are a potential security hole if you leave
275			them on the system after porting. When you've finished migrating your data,
276			continue to the next section.
277	swift	1.19	</p>
278
279	swift	1.1	</body>
280			</section>
281			<section>
282			<title>Configuring PAM</title>
283			<body>
284
285			<p>
286	swift	1.20	First, we will configure PAM to allow LDAP authorization. Install
287	jkt	1.32	<c>sys-auth/pam_ldap</c> so that PAM supports LDAP authorization, and
288			<c>sys-auth/nss_ldap</c> so that your system can cope with LDAP servers for
289	swift	1.20	additional information (used by <path>nsswitch.conf</path>).
290			</p>
291
292			<pre caption="Installing pam_ldap and nss_ldap">
293			# <i>emerge pam_ldap nss_ldap</i>
294			</pre>
295
296			<p>
297	swift	1.37	Now add the following lines in the right places to
298			<path>/etc/pam.d/system-auth</path>:
299	swift	1.1	</p>
300
301			<pre caption="/etc/pam.d/system-auth">
302	nightmorph	1.36	<comment># Note: only add them. Don't kill stuff already in there or your box won't let you login again!</comment>
303
304			auth sufficient pam_ldap.so use_first_pass
305			account sufficient pam_ldap.so
306			password sufficient pam_ldap.so use_authtok use_first_pass
307			session optional pam_ldap.so
308
309			<comment># Example file:</comment>
310			#%PAM-1.0
311
312			auth required pam_env.so
313			auth sufficient pam_unix.so try_first_pass likeauth nullok
314			<i>auth sufficient pam_ldap.so use_first_pass</i>
315			auth required pam_deny.so
316
317			<i>account sufficient pam_ldap.so</i>
318			account required pam_unix.so
319
320			password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 try_first_pass retry=3
321			password sufficient pam_unix.so try_first_pass use_authtok nullok md5 shadow
322			<i>password sufficient pam_ldap.so use_authtok use_first_pass</i>
323			password required pam_deny.so
324
325			session required pam_limits.so
326			session required pam_unix.so
327			<i>session optional pam_ldap.so</i>
328
329	swift	1.1	</pre>
330
331			<p>
332			Now change <path>/etc/ldap.conf</path> to read:
333			</p>
334
335			<pre caption="/etc/ldap.conf">
336			<comment>#host 127.0.0.1</comment>
337			<comment>#base dc=padl,dc=com</comment>
338
339			suffix "dc=genfic,dc=com"
340			<comment>#rootbinddn uid=root,ou=People,dc=genfic,dc=com</comment>
341
342	nightmorph	1.36	uri ldap://auth.genfic.com/
343	swift	1.1	pam_password exop
344
345			ldap_version 3
346			pam_filter objectclass=posixAccount
347			pam_login_attribute uid
348			pam_member_attribute memberuid
349			nss_base_passwd ou=People,dc=genfic,dc=com
350			nss_base_shadow ou=People,dc=genfic,dc=com
351			nss_base_group ou=Group,dc=genfic,dc=com
352			nss_base_hosts ou=Hosts,dc=genfic,dc=com
353
354			scope one
355			</pre>
356
357			<p>
358	swift	1.37	Next, copy over the (OpenLDAP) <path>ldap.conf</path> file from the server to
359	swift	1.27	the client so the clients are aware of the LDAP environment:
360			</p>
361
362			<pre caption="Copying over the OpenLDAP ldap.conf">
363			<comment>(Substitute ldap-server with your LDAP server name)</comment>
364			# <i>scp ldap-server:/etc/openldap/ldap.conf /etc/openldap</i>
365			</pre>
366
367			<p>
368	swift	1.1	Finally, configure your clients so that they check the LDAP for system
369			accounts:
370			</p>
371
372			<pre caption="/etc/nsswitch.conf">
373			passwd: files ldap
374			group: files ldap
375	swift	1.3	shadow: files ldap
376	swift	1.1	</pre>
377
378			<p>
379			To test the changes, type:
380			</p>
381
382			<pre caption="Testing LDAP Auth">
383			# <i>getent passwd\|grep 0:0</i>
384
385	neysx	1.23	<comment>(You should get two entries back:)</comment>
386	swift	1.37	root:x:0:0:root:/root:/bin/bash
387	swift	1.1	root:x:0:0:root:/root:/bin/bash
388			</pre>
389
390			<p>
391			If you noticed one of the lines you pasted into your <path>/etc/ldap.conf</path>
392	swift	1.37	was commented out (the <c>rootbinddn</c> line): you don't need it unless you
393			want to change a user's password as superuser. In this case you need to echo
394			the root password to <path>/etc/ldap.secret</path> in plaintext. This is
395			<brite>DANGEROUS</brite> and should be chmoded to 600. What I do is keep that
396			file blank and when I need to change someones password thats both in the ldap
397			and <path>/etc/passwd</path> I put the pass in there for 10 seconds while I
398	swift	1.1	change it and remove it when I'm done.
399			</p>
400
401			</body>
402			</section>
403	swift	1.20	</chapter>
404	swift	1.1
405	swift	1.20	<chapter>
406			<title>LDAP Server Security Settings</title>
407	swift	1.1	<section>
408			<title>OpenLDAP permissions</title>
409			<body>
410
411			<p>
412			If we take a look at <path>/etc/openldap/slapd.conf</path> you'll see
413			that you can specify the ACLs (permissions if you like) of what data
414			users can read and/or write:
415			</p>
416
417			<pre caption="/etc/openldap/slapd.conf">
418			access to *
419	nightmorph	1.40	by dn="uid=root,ou=People,dc=genfic,dc=com" write
420	swift	1.1	by users read
421			by anonymous auth
422	swift	1.15
423	swift	1.8	access to attrs=userPassword,gecos,description,loginShell
424			by self write
425	swift	1.1	</pre>
426
427			<p>
428	swift	1.37	This gives you access to everything a user should be able to change. If it's
429			your information, then you got write access to it; if it's another user their
430			information then you can read it; anonymous people can send a login/pass to get
431			logged in. There are four levels, ranking them from lowest to greatest: <c>auth
432	swift	1.8	search read write</c>.
433	swift	1.1	</p>
434
435			<p>
436			The next ACL is a bit more secure as it blocks normal users to read
437			other people their shadowed password:
438			</p>
439
440			<pre caption="/etc/openldap/slapd.conf">
441	swift	1.22	access to attrs="userPassword"
442	nightmorph	1.40	by dn="uid=root,ou=People,dc=genfic,dc=com" write
443	swift	1.15	by dn="uid=John,ou=People,dc=genfic,dc=com" write
444	swift	1.1	by anonymous auth
445			by self write
446	swift	1.15	by * none
447	swift	1.37
448	swift	1.1	access to *
449			by dn="uid=root,ou=People,dc=genfic,dc=com" write
450	nightmorph	1.40	by dn="uid=John,ou=People,dc=genfic,dc=com" write
451	fox2mike	1.30	by * search
452	swift	1.1	</pre>
453
454			<p>
455			This example gives root and John access to read/write/search
456	swift	1.37	for everything in the the tree below <path>dc=genfic,dc=com</path>. This also
457			lets users change their own <path>userPassword</path>'s. As for the ending
458			statement everyone else just has a search ability meaning they can fill in a
459			search filter, but can't read the search results. Now you can have multiple
460			acls but the rule of the thumb is it processes from bottom up, so your
461	swift	1.1	toplevel should be the most restrictive ones.
462			</p>
463
464			</body>
465			</section>
466			</chapter>
467
468			<chapter>
469			<title>Working with OpenLDAP</title>
470			<section>
471			<title>Maintaining the directory</title>
472			<body>
473
474			<p>
475	nightmorph	1.36	You can start using the directory to authenticate users in
476	nightmorph	1.43	apache/proftpd/qmail/samba. You can manage it with phpldapadmin, diradm,
477			jxplorer, or lat, which provide easy management interfaces.
478	swift	1.1	</p>
479
480			</body>
481			</section>
482			</chapter>
483
484			<chapter>
485			<title>Acknowledgements</title>
486			<section>
487			<body>
488
489			<p>
490	swift	1.37	We would like to thank Matt Heler for lending us his box for the purpose of
491	swift	1.1	this guide. Thanks also go to the cool guys in #ldap @ irc.freenode.net
492			</p>
493
494			</body>
495			</section>
496			</chapter>
497			</guide>