source: branches/fc13-dev/server/doc/install-ldap @ 1677

Last change on this file since 1677 was 1677, checked in by ezyang, 12 years ago
More updates.
File size: 12.4 KB
Line 
1To set up a new LDAP server:
2
3- Install the RPM 389-ds-base with yum
4  root# yum install -y 389-ds-base
5- We want to run the directory server as its own user, so create fedora-ds
6  root# env NSS_NONLOCAL_IGNORE=1 useradd -r -d /var/lib/dirsrv fedora-ds
7- root# yum install -y policycoreutils-python
8- Temporarily move away the existing slapd-scripts folder
9  root# mv /etc/dirsrv/slapd-scripts{,.bak}
10- root# /usr/sbin/setup-ds.pl
11    - Choose a typical install
12    - Tell it to use the fedora-ds user and group
13    - Directory server identifier: scripts
14        Needed to remove this from the config file first
15    - Suffix: dc=scripts,dc=mit,dc=edu
16    - Input directory manager password
17      (this can be found in  ~/.ldapvirc)
18- Move the schema back
19  root# cp -R /etc/dirsrv/slapd-scripts.bak/{.svn,*} /etc/dirsrv/slapd-scripts
20  root# rm -Rf /etc/dirsrv/slapd-scripts.bak
21- yum install ldapvi
22- Check if dirsrv starts: /sbin/service dirsrv start
23  then turn it back off: service dirsrv stop
24- Apply the following configuration changes.  If you're editing
25  dse.ldif, you don't want dirsrv to be on, otherwise it will
26  overwrite your changes. [XXX: show how to do these changes with
27  dsconf, which is the "blessed" method]
28
29# Inside cn=config.  These changes definitely require a restart.
30nsslapd-ldapifilepath: /var/run/dirsrv/slapd-scripts.socket
31nsslapd-ldapilisten: on
32
33# Add these blocks
34
35# mapname, mapping, sasl, config
36# This is the most liberal mapping you can have for SASL: you can
37# basically add authentication for any given GSSAPI mechanism by
38# explicitly creating the UID for that SASL string.
39dn: cn=mapname,cn=mapping,cn=sasl,cn=config
40objectClass: top
41objectClass: nsSaslMapping
42cn: mapname
43nsSaslMapRegexString: \(.*\)
44nsSaslMapBaseDNTemplate: uid=\1,ou=People,dc=scripts,dc=mit,dc=edu
45nsSaslMapFilterTemplate: (objectClass=posixAccount)
46
47- Put LDAP keytab (ldap/hostname.mit.edu) in /etc/dirsrv/keytab.  Make
48  sure you chown/chgrp it to be readable by fedora-ds
49- Uncomment and modify in /etc/sysconfig/dirsrv: KRB5_KTNAME=/etc/dirsrv/keytab ; export KRB5_KTNAME
50- chown fedora-ds:fedora-ds /var/run/dirsrv
51- chmod 755 /var/run/dirsrv
52- /sbin/service dirsrv start
53- Use ldapvi -b cn=config to add these indexes (8 of them):
54
55add cn=apacheServerName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
56objectClass: top
57objectClass: nsIndex
58cn: apacheServerName
59nsSystemIndex: false
60nsIndexType: eq
61nsIndexType: pres
62
63add cn=apacheServerAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
64objectClass: top
65objectClass: nsIndex
66cn: apacheServerAlias
67nsSystemIndex: false
68nsIndexType: eq
69nsIndexType: pres
70
71add cn=scriptsVhostName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
72objectClass: top
73objectClass: nsIndex
74cn: scriptsVhostName
75nsSystemIndex: false
76nsIndexType: eq
77nsIndexType: pres
78
79add cn=scriptsVhostAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
80objectClass: top
81objectClass: nsIndex
82cn: scriptsVhostAlias
83nsSystemIndex: false
84nsIndexType: eq
85nsIndexType: pres
86
87add cn=scriptsVhostAccount, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
88objectClass: top
89objectClass: nsIndex
90cn: scriptsVhostAccount
91nsSystemIndex: false
92nsIndexType: eq
93nsIndexType: pres
94
95add cn=memberuid, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
96objectClass: top
97objectClass: nsIndex
98cn: memberuid
99nsSystemIndex: false
100nsIndexType: eq
101nsIndexType: pres
102
103add cn=uidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
104objectClass: top
105objectClass: nsIndex
106cn: uidnumber
107nsSystemIndex: false
108nsIndexType: eq
109nsIndexType: pres
110
111add cn=gidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
112objectClass: top
113objectClass: nsIndex
114cn: gidnumber
115nsSystemIndex: false
116nsIndexType: eq
117nsIndexType: pres
118
119- Build the indexes for all the fields:
120
121    /usr/lib64/dirsrv/slapd-scripts/db2index.pl -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
122
123  (/etc/signup-ldap-pw is the LDAP root password, make sure it's
124  chmodded correctly and chowned to signup. Also, make sure it doesn't
125  have a trailing newline!)
126
127-  Watch for the indexing operations to finish with this command:
128
129    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
130
131  (look for nktaskstatus)
132
133- Set up replication.
134
135  We used to tell people to go execute
136  http://directory.fedoraproject.org/sources/contrib/mmr.pl manually
137  (manually because that script assumes only two masters and we have
138  every one of our servers set up as a master.)  However, those
139  instructions are inaccurate, because we use GSSAPI, not SSL and
140  because the initializing procedure is actually prone to a race
141  condition.  Here are some better instructions.
142
143  LDAP replication is based around producers and consumers.  Producers
144  push changes in LDAP to consumers: these arrangements are called
145  "replication agreements" and the producer will hold a
146  nsDS5ReplicationAgreement object that represents this commitment,
147  as well as some extra configuration to say who consumers will accept
148  replication data from (a nsDS5Replica).
149
150  The procedure, at a high level, is this:
151
152    1. Pick an arbitrary existing master.  The current server will
153       be configured as a slave to that master.  Initialize a changelog,
154       then request a replication to populate our server with
155       information.
156
157            M1 <---> M2 ---> S
158
159    2. Configure the new server to be replicated back.
160
161            M1 <---> M2 <---> S
162
163    3. Set up the rest of the replication agreements at your leisure.
164
165                M1 <---> M2
166                ^         ^
167                |         |
168                +--> S <--+
169
170  Here's how you do it.
171
172    1. Pull open the replication part of the database. It's fairly empty
173       right now.
174
175        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
176
177    2. Configure the server $SLAVE (this server) to accept $MASTER
178       replications by adding the following LDAP entries:
179
180add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
181objectClass: top
182objectClass: nsDS5Replica
183cn: replica
184nsDS5ReplicaId: $REPLICA_ID
185nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
186nsDS5Flags: 1
187nsDS5ReplicaBindDN: uid=ldap/bees-knees.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
188nsDS5ReplicaBindDN: uid=ldap/busy-beaver.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
189nsDS5ReplicaBindDN: uid=ldap/cats-whiskers.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
190nsDS5ReplicaBindDN: uid=ldap/pancake-bunny.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
191nsDS5ReplicaBindDN: uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
192nsDS5ReplicaBindDN: uid=ldap/real-mccoy.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
193nsDS5ReplicaBindDN: uid=ldap/better-mousetrap.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
194nsDS5ReplicaBindDN: uid=ldap/old-faithful.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
195# ADD SERVERS HERE AS YOU ADD NEW SERVERS
196nsds5ReplicaPurgeDelay: 604800
197nsds5ReplicaLegacyConsumer: off
198nsDS5ReplicaType: 3
199
200        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
201        out.)  You might wonder why we are binding to all servers;
202        weren't we going to replicate from only one server?  That is
203        correct, however, simply binding won't mean we will receive
204        updates; we have to setup the $MASTER to send data $SLAVE.
205
206    3. Although we allowed those uids to bind, that user information
207       doesn't exist on $SLAVE yet.  So you'll need to create the entry
208       for just $MASTER.
209
210add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
211uid: ldap/$MASTER
212objectClass: account
213objectClass: top
214
215    4. Though our $SLAVE will not be making changes to LDAP, we need to
216       initialize the changelog because we intend to be able to do this
217       later.
218
219add cn=changelog5,cn=config
220objectclass: top
221objectclass: extensibleObject
222cn: changelog5
223nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
224
225    5. Ok, now go to your $MASTER server that you picked (it should have
226       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
227       it to replicate to $SLAVE.
228
229       WARNING: There is a known bug doing full updates from 1.2.6 to
230       1.2.6, see https://bugzilla.redhat.com/show_bug.cgi?id=637852
231
232add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
233objectClass: top
234objectClass: nsDS5ReplicationAgreement
235cn: "GSSAPI Replication to $SLAVE"
236cn: GSSAPI Replication to $SLAVE
237nsDS5ReplicaHost: $SLAVE
238nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
239nsDS5ReplicaPort: 389
240nsDS5ReplicaTransportInfo: LDAP
241nsDS5ReplicaBindDN:
242uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
243nsDS5ReplicaBindMethod: SASL/GSSAPI
244nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
245nsDS5ReplicaTimeout: 120
246
247    4. Run the replication.  This is perhaps the most risky step of
248    the process; see below for help debugging problems.
249
250# under cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
251nsDS5BeginReplicaRefresh: start
252
253    5. Check that the replication is running; the status will be stored
254    in the object we've been mucking around with.
255
256    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
257    for more information.  It might be because fedora-ds can't read
258    /etc/dirsrv/keytab
259
260    6. Replicate in the other direction.  On $MASTER, add $SLAVE
261    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
262    Also, add an account for $SLAVE
263
264add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
265uid: ldap/$SLAVE
266objectClass: account
267objectClass: top
268
269    On $SLAVE,
270
271add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
272objectClass: top
273objectClass: nsDS5ReplicationAgreement
274cn: "GSSAPI Replication to $MASTER"
275cn: GSSAPI Replication to $MASTER
276nsDS5ReplicaHost: $MASTER
277nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
278nsDS5ReplicaPort: 389
279nsDS5ReplicaTransportInfo: LDAP
280nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
281nsDS5ReplicaBindMethod: SASL/GSSAPI
282nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
283nsDS5ReplicaTimeout: 120
284
285    If you get a really scary internal server error, that might mean you
286    forgot to initialize the changelog.  Remove the replication
287    agreement (you'll need to turn off dirsrv), add the changelog, and
288    then try again.
289
290Troubleshooting
291===============
292
293LDAP multimaster replication can fail in a number of colorful ways;
294combine that with GSSAPI authentication and it goes exponential.
295
296If authentication is failing with LDAP error 49, check if:
297
298    * /etc/dirsrv/keytab
299    * fedora-ds is able to read /etc/dirsrv/keytab
300    * /etc/hosts has not been modified by Network Manager (you
301      /did/ uninstall it, right? Right?)
302
303If the failure is local to a single master, usually you can recover
304by asking another master to refresh that master with:
305
306nsDS5BeginReplicaRefresh: start
307
308In practice, we've also had problems with this technique.  Some of them
309include:
310
311* Something like https://bugzilla.redhat.com/show_bug.cgi?id=547503
312  on Fedora 11 ns-slapd, where replication is turned off to do the
313  replication, but then it wedges and you need to forcibly kill the
314  process.
315
316* Failed LDAP authentication because another master attempted to do
317  an incremental update.
318
319* Repropagation of the error because the corrupt master thinks it still
320  should push updates.
321
322So the extremely safe method to bring up a crashed master is as follows:
323
3241. Disable all incoming and outgoing replication agreements by editing
325   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
326
327   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
328
329   and all of the push agreements.  Deleting them outright works, but
330   means you'll have to reconstruct all of the agreements from scratch.
331
3322. Bring up the server.
333
3343. Accept incoming replication data from a single server.
335
3364. Initiate a full update from that server.
337
3385. Finish setting up replication as described above.
339
340If your database gets extremely fucked, other servers may not be able
341to authenticate because your authentication information has gone missing.
342In that case, the minimal set of entries you need is:
343
344add dc=scripts,dc=mit,dc=edu
345objectClass: top
346objectClass: domain
347dc: scripts
348
349add ou=People,dc=scripts,dc=mit,dc=edu
350objectClass: top
351objectClass: organizationalunit
352ou: People
353
354add uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
355objectClass: account
356objectClass: top
357uid: ldap/whole-enchilada.mit.edu
Note: See TracBrowser for help on using the repository browser.