source: trunk/server/doc/install-ldap @ 2477

Last change on this file since 2477 was 2246, checked in by ezyang, 12 years ago
Reintegrate Fedora 17 development branch into trunk.
File size: 14.5 KB
Line 
1# b
2# To set up a new LDAP server:
3
4# Temporarily move away the existing slapd-scripts folder
5mv /etc/dirsrv/slapd-scripts{,.bak}
6
7# Setup directory server
8/usr/sbin/setup-ds.pl
9#   - Choose a typical install
10#   - Tell it to use the fedora-ds user and group
11#   - Directory server identifier: scripts
12#   - Suffix: dc=scripts,dc=mit,dc=edu
13#   - Input directory manager password
14#     (this can be found in  ~/.ldapvirc)
15
16# Move the schema back
17cp -R /etc/dirsrv/slapd-scripts.bak/* /etc/dirsrv/slapd-scripts
18rm -Rf /etc/dirsrv/slapd-scripts.bak
19
20# Check and make sure the sysconfig references the correct keytab
21svn revert /etc/sysconfig/dirsrv-scripts
22
23# Turn dirsrv off:
24systemctl stop dirsrv@scripts.service
25
26# Apply the following configuration changes.  If you're editing
27# dse.ldif, you don't want dirsrv to be on, otherwise it will
28# overwrite your changes. [XXX: show how to do these changes with
29# dsconf, which is the "blessed" method, although it seems
30# dsconf only exists for Red Hat]
31
32vim /etc/dirsrv/slapd-scripts/dse.ldif
33<<<EOF
34
35# Inside cn=config.  These changes definitely require a restart.
36nsslapd-ldapilisten: on
37nsslapd-syntaxcheck: off
38
39# We need to turn off syntax check because our schema is wrong and too
40# restrictive on some value. This should get fixed.
41
42# Add these blocks
43
44# mapname, mapping, sasl, config
45# This is the most liberal mapping you can have for SASL: you can
46# basically add authentication for any given GSSAPI mechanism by
47# explicitly creating the UID for that SASL string.
48dn: cn=mapname,cn=mapping,cn=sasl,cn=config
49objectClass: top
50objectClass: nsSaslMapping
51cn: mapname
52nsSaslMapRegexString: \(.*\)
53nsSaslMapBaseDNTemplate: uid=\1,ou=People,dc=scripts,dc=mit,dc=edu
54nsSaslMapFilterTemplate: (objectClass=posixAccount)
55
56EOF;
57
58systemctl start dirsrv@scripts.service
59
60ldapvi -b cn=config
61# Add these indexes (8 of them):
62
63<<<EOF
64
65add cn=apacheServerName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
66objectClass: top
67objectClass: nsIndex
68cn: apacheServerName
69nsSystemIndex: false
70nsIndexType: eq
71nsIndexType: pres
72
73add cn=apacheServerAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
74objectClass: top
75objectClass: nsIndex
76cn: apacheServerAlias
77nsSystemIndex: false
78nsIndexType: eq
79nsIndexType: pres
80
81add cn=scriptsVhostName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
82objectClass: top
83objectClass: nsIndex
84cn: scriptsVhostName
85nsSystemIndex: false
86nsIndexType: eq
87nsIndexType: pres
88
89add cn=scriptsVhostAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
90objectClass: top
91objectClass: nsIndex
92cn: scriptsVhostAlias
93nsSystemIndex: false
94nsIndexType: eq
95nsIndexType: pres
96
97add cn=scriptsVhostAccount, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
98objectClass: top
99objectClass: nsIndex
100cn: scriptsVhostAccount
101nsSystemIndex: false
102nsIndexType: eq
103nsIndexType: pres
104
105add cn=memberuid, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
106objectClass: top
107objectClass: nsIndex
108cn: memberuid
109nsSystemIndex: false
110nsIndexType: eq
111nsIndexType: pres
112
113add cn=uidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
114objectClass: top
115objectClass: nsIndex
116cn: uidnumber
117nsSystemIndex: false
118nsIndexType: eq
119nsIndexType: pres
120
121add cn=gidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
122objectClass: top
123objectClass: nsIndex
124cn: gidnumber
125nsSystemIndex: false
126nsIndexType: eq
127nsIndexType: pres
128
129EOF;
130
131- Build the indexes for all the fields:
132
133    /usr/lib64/dirsrv/slapd-scripts/db2index.pl -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
134
135  (/etc/signup-ldap-pw is the LDAP root password, make sure it's
136  chmodded correctly and chowned to signup. Also, make sure it doesn't
137  have a trailing newline!)
138
139-  Watch for the indexing operations to finish with this command:
140
141    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
142
143  (look for nktaskstatus)
144
145- Set up replication.
146
147  We used to tell people to go execute
148  http://directory.fedoraproject.org/sources/contrib/mmr.pl manually
149  (manually because that script assumes only two masters and we have
150  every one of our servers set up as a master.)  However, those
151  instructions are inaccurate, because we use GSSAPI, not SSL and
152  because the initializing procedure is actually prone to a race
153  condition.  Here are some better instructions.
154
155  LDAP replication is based around producers and consumers.  Producers
156  push changes in LDAP to consumers: these arrangements are called
157  "replication agreements" and the producer will hold a
158  nsDS5ReplicationAgreement object that represents this commitment,
159  as well as some extra configuration to say who consumers will accept
160  replication data from (a nsDS5Replica).
161
162  The procedure, at a high level, is this:
163
164    1. Pick an arbitrary existing master.  The current server will
165       be configured as a slave to that master.  Initialize a changelog,
166       then request a replication to populate our server with
167       information.
168
169            M1 <---> M2 ---> S
170
171    2. Configure the new server to be replicated back.
172
173            M1 <---> M2 <---> S
174
175    3. Set up the rest of the replication agreements.
176
177                M1 <---> M2
178                ^         ^
179                |         |
180                +--> S <--+
181
182    4. Push a change from every existing server (to the new server), and
183       then a change from the new server to (all) the existing servers.
184       In addition to merely testing that replication works, this will
185       set up the servers' changelogs properly.
186
187       If this step is not completed before any server's LDAP server
188       shuts down, then the replication agreements will fall apart the
189       next time a change is made. You may wish to intentionally reboot
190       any servers that look like they want to crash _before_ beginning
191       this process.
192
193  Here's how you do it.
194
195  NOTE: There's this spiffy new tool MMR hammer which automates some of
196  this process.  Check the "MMR Hammer" sections to see how.  Install it
197  here:  https://github.com/ezyang/mmr-hammer
198
199    0. Tell -c scripts not to go off and reboot servers until you're
200       done (or to get any rebooting done with first).
201
202    1. Pull open the replication part of the database. It's fairly empty
203       right now.
204
205        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
206
207    2. Configure the server $SLAVE (this server) to accept $MASTER
208       replications by adding the following LDAP entries:
209
210add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
211objectClass: top
212objectClass: nsDS5Replica
213cn: replica
214nsDS5ReplicaId: $REPLICA_ID
215nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
216nsDS5Flags: 1
217nsDS5ReplicaBindDN: uid=ldap/bees-knees.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
218nsDS5ReplicaBindDN: uid=ldap/busy-beaver.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
219nsDS5ReplicaBindDN: uid=ldap/cats-whiskers.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
220nsDS5ReplicaBindDN: uid=ldap/pancake-bunny.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
221nsDS5ReplicaBindDN: uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
222nsDS5ReplicaBindDN: uid=ldap/real-mccoy.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
223nsDS5ReplicaBindDN: uid=ldap/better-mousetrap.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
224nsDS5ReplicaBindDN: uid=ldap/old-faithful.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
225nsDS5ReplicaBindDN: uid=ldap/shining-armor.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
226nsDS5ReplicaBindDN: uid=ldap/golden-egg.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
227nsDS5ReplicaBindDN: uid=ldap/miracle-cure.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
228nsDS5ReplicaBindDN: uid=ldap/lucky-star.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
229nsds5ReplicaPurgeDelay: 604800
230nsds5ReplicaLegacyConsumer: off
231nsDS5ReplicaType: 3
232
233        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
234        out.)  You might wonder why we are binding to all servers;
235        weren't we going to replicate from only one server?  That is
236        correct, however, simply binding won't mean we will receive
237        updates; we have to setup the $MASTER to send data $SLAVE.
238
239    3. Although we allowed those uids to bind, that user information
240       doesn't exist on $SLAVE yet.  So you'll need to create the entry
241       for just $MASTER.
242
243       REMEMBER: You need to use FOO.mit.edu for the names!  Otherwise you will get
244       unauthorized errors.
245
246add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
247uid: ldap/$MASTER
248objectClass: account
249objectClass: top
250
251    4. Though our $SLAVE will not be making changes to LDAP, we need to
252       initialize the changelog because we intend to be able to do this
253       later.
254
255add cn=changelog5,cn=config
256objectclass: top
257objectclass: extensibleObject
258cn: changelog5
259nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
260
261    5. Ok, now go to your $MASTER server that you picked (it should have
262       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
263       it to replicate to $SLAVE.
264
265       The last line runs the replication.  This is perhaps the most
266       risky step of the process; see below for help debugging problems.
267
268       MMR Hammer:
269        mmr-hammer -h $MASTER init agreements $SLAVE
270        mmr-hammer -h $MASTER update $SLAVE # XXX pick a better name
271
272        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
273
274add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
275objectClass: top
276objectClass: nsDS5ReplicationAgreement
277cn: "GSSAPI Replication to $SLAVE"
278cn: GSSAPI Replication to $SLAVE
279nsDS5ReplicaHost: $SLAVE
280nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
281nsDS5ReplicaPort: 389
282nsDS5ReplicaTransportInfo: LDAP
283nsDS5ReplicaBindDN: uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
284nsDS5ReplicaBindMethod: SASL/GSSAPI
285nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
286nsDS5ReplicaTimeout: 120
287nsDS5BeginReplicaRefresh: start
288
289    5. Check that the replication is running; the status will be stored
290    in the object we've been mucking around with.
291
292    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
293    for more information.  It might be because fedora-ds can't read
294    /etc/dirsrv/keytab or because you setup the account on the SLAVE
295    incorrectly.
296
297    6. Replicate in the other direction.  On $MASTER, add $SLAVE
298    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
299    Also, add an account for $SLAVE if it doesn't exist already.
300
301add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
302uid: ldap/$SLAVE
303objectClass: account
304objectClass: top
305
306    On $SLAVE,
307
308       MMR Hammer: mmr-hammer -h $SLAVE init agreements $MASTER
309
310add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
311objectClass: top
312objectClass: nsDS5ReplicationAgreement
313cn: "GSSAPI Replication to $MASTER"
314cn: GSSAPI Replication to $MASTER
315nsDS5ReplicaHost: $MASTER
316nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
317nsDS5ReplicaPort: 389
318nsDS5ReplicaTransportInfo: LDAP
319nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
320nsDS5ReplicaBindMethod: SASL/GSSAPI
321nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
322nsDS5ReplicaTimeout: 120
323
324    If you get a really scary internal server error, that might mean you
325    forgot to initialize the changelog.  Remove the replication
326    agreement (you'll need to turn off dirsrv), add the changelog, and
327    then try again.
328
329    7. Repeat step 6 to complete the graph of replications (i.e., from
330    every other server to the new server, and from the new server to
331    every other server).
332
333    Note the only difference between steps 5 and 6 is the lack of
334    nsDS5ReplicaRefresh: start. That only needs to be done once, to the
335    new server.
336
337    With MMR hammer, that's something like:
338
339        for i in $SERVER_NAMES; do mmr-hammer -h $i init agreements $SERVER_NAMES; done
340
341    8. If at this point you look at the new server's changelog with
342    cl-dump (preferably /mit/scripts/admin/cl-dump.pl, to not prompt you
343    for a password), you won't see the servers you added in step 7. So,
344    from each of those servers, make a change to some record so it gets
345    propagated to the new server, and then one from the new server so it
346    gets propagated to all the existing servers' changelogs. This is
347    also good for making sure the replication agreements actually work.
348
349    With MMR hammer, that's something like:
350
351        for i in $SERVER_NAMES; do mmr-hammer -h $i test; sleep 20; done
352
353Troubleshooting
354===============
355
356LDAP multimaster replication can fail in a number of colorful ways;
357combine that with GSSAPI authentication and it goes exponential.
358
359If authentication is failing with LDAP error 49, check if:
360
361    * /etc/dirsrv/keytab
362    * fedora-ds is able to read /etc/dirsrv/keytab
363    * /etc/hosts has not been modified by Network Manager (you
364      /did/ uninstall it, right? Right?)
365
366If the failure is local to a single master, usually you can recover
367by asking another master to refresh that master with:
368
369nsDS5BeginReplicaRefresh: start
370
371In practice, we've also had problems with this technique.  Some of them
372include:
373
374* Something like https://bugzilla.redhat.com/show_bug.cgi?id=547503
375  on Fedora 11 ns-slapd, where replication is turned off to do the
376  replication, but then it wedges and you need to forcibly kill the
377  process.
378
379* Failed LDAP authentication because another master attempted to do
380  an incremental update.
381
382* Repropagation of the error because the corrupt master thinks it still
383  should push updates.
384
385So the extremely safe method to bring up a crashed master is as follows:
386
3871. Disable all incoming and outgoing replication agreements by editing
388   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
389
390   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
391
392   and all of the push agreements.  Deleting them outright works, but
393   means you'll have to reconstruct all of the agreements from scratch.
394
3952. Bring up the server.
396
3973. Accept incoming replication data from a single server.
398
3994. Initiate a full update from that server.
400
4015. Finish setting up replication as described above.
402
403If your database gets extremely fucked, other servers may not be able
404to authenticate because your authentication information has gone missing.
405In that case, the minimal set of entries you need is:
406
407add dc=scripts,dc=mit,dc=edu
408objectClass: top
409objectClass: domain
410dc: scripts
411
412add ou=People,dc=scripts,dc=mit,dc=edu
413objectClass: top
414objectClass: organizationalunit
415ou: People
416
417add uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
418objectClass: account
419objectClass: top
420uid: ldap/whole-enchilada.mit.edu
Note: See TracBrowser for help on using the repository browser.