source: branches/fc15-dev/server/doc/install-ldap @ 2019

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