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

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