source: trunk/ldap/doc/install-ldap @ 2758

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