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

Last change on this file since 1994 was 1986, checked in by geofft, 13 years ago
Fix notes about changelog initialization
File size: 13.9 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       If this step is not completed before any server's LDAP server
177       shuts down, then the replication agreements will fall apart the
178       next time a change is made. You may wish to intentionally reboot
179       any servers that look like they want to crash _before_ beginning
180       this process.
181
182  Here's how you do it.
183
184    0. Tell -c scripts not to go off and reboot servers until you're
185       done (or to get any rebooting done with first).
186
187    1. Pull open the replication part of the database. It's fairly empty
188       right now.
189
190        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
191
192    2. Configure the server $SLAVE (this server) to accept $MASTER
193       replications by adding the following LDAP entries:
194
195add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
196objectClass: top
197objectClass: nsDS5Replica
198cn: replica
199nsDS5ReplicaId: $REPLICA_ID
200nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
201nsDS5Flags: 1
202nsDS5ReplicaBindDN: uid=ldap/bees-knees.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
203nsDS5ReplicaBindDN: uid=ldap/busy-beaver.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
204nsDS5ReplicaBindDN: uid=ldap/cats-whiskers.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
205nsDS5ReplicaBindDN: uid=ldap/pancake-bunny.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
206nsDS5ReplicaBindDN: uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
207nsDS5ReplicaBindDN: uid=ldap/real-mccoy.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
208nsDS5ReplicaBindDN: uid=ldap/better-mousetrap.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
209nsDS5ReplicaBindDN: uid=ldap/old-faithful.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
210nsDS5ReplicaBindDN: uid=ldap/shining-armor.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
211nsds5ReplicaPurgeDelay: 604800
212nsds5ReplicaLegacyConsumer: off
213nsDS5ReplicaType: 3
214
215        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
216        out.)  You might wonder why we are binding to all servers;
217        weren't we going to replicate from only one server?  That is
218        correct, however, simply binding won't mean we will receive
219        updates; we have to setup the $MASTER to send data $SLAVE.
220
221    3. Although we allowed those uids to bind, that user information
222       doesn't exist on $SLAVE yet.  So you'll need to create the entry
223       for just $MASTER.
224
225add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
226uid: ldap/$MASTER
227objectClass: account
228objectClass: top
229
230    4. Though our $SLAVE will not be making changes to LDAP, we need to
231       initialize the changelog because we intend to be able to do this
232       later.
233
234add cn=changelog5,cn=config
235objectclass: top
236objectclass: extensibleObject
237cn: changelog5
238nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
239
240    5. Ok, now go to your $MASTER server that you picked (it should have
241       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
242       it to replicate to $SLAVE.
243
244       The last line runs the replication.  This is perhaps the most
245       risky step of the process; see below for help debugging problems.
246
247       WARNING: There is a known bug doing full updates from 1.2.6 to
248       1.2.6, see https://bugzilla.redhat.com/show_bug.cgi?id=637852
249
250add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
251objectClass: top
252objectClass: nsDS5ReplicationAgreement
253cn: "GSSAPI Replication to $SLAVE"
254cn: GSSAPI Replication to $SLAVE
255nsDS5ReplicaHost: $SLAVE
256nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
257nsDS5ReplicaPort: 389
258nsDS5ReplicaTransportInfo: LDAP
259nsDS5ReplicaBindDN: uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
260nsDS5ReplicaBindMethod: SASL/GSSAPI
261nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
262nsDS5ReplicaTimeout: 120
263nsDS5BeginReplicaRefresh: start
264
265    5. Check that the replication is running; the status will be stored
266    in the object we've been mucking around with.
267
268    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
269    for more information.  It might be because fedora-ds can't read
270    /etc/dirsrv/keytab
271
272    6. Replicate in the other direction.  On $MASTER, add $SLAVE
273    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
274    Also, add an account for $SLAVE
275
276add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
277uid: ldap/$SLAVE
278objectClass: account
279objectClass: top
280
281    On $SLAVE,
282
283add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
284objectClass: top
285objectClass: nsDS5ReplicationAgreement
286cn: "GSSAPI Replication to $MASTER"
287cn: GSSAPI Replication to $MASTER
288nsDS5ReplicaHost: $MASTER
289nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
290nsDS5ReplicaPort: 389
291nsDS5ReplicaTransportInfo: LDAP
292nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
293nsDS5ReplicaBindMethod: SASL/GSSAPI
294nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
295nsDS5ReplicaTimeout: 120
296
297    If you get a really scary internal server error, that might mean you
298    forgot to initialize the changelog.  Remove the replication
299    agreement (you'll need to turn off dirsrv), add the changelog, and
300    then try again.
301
302    7. Repeat step 6 to complete the graph of replications (i.e., from
303    every other server to the new server, and from the new server to
304    every other server).
305
306    Note the only difference between steps 5 and 6 is the lack of
307    nsDS5ReplicaRefresh: start. That only needs to be done once, to the
308    new server.
309
310    8. If at this point you look at the new server's changelog with
311    cl-dump (preferably /mit/scripts/admin/cl-dump.pl, to not prompt you
312    for a password), you won't see the servers you added in step 7. So,
313    from each of those servers, make a change to some record so it gets
314    propagated to the new server, and then one from the new server so it
315    gets propagated to all the existing servers' changelogs. This is
316    also good for making sure the replication agreements actually work.
317
318Troubleshooting
319===============
320
321LDAP multimaster replication can fail in a number of colorful ways;
322combine that with GSSAPI authentication and it goes exponential.
323
324If authentication is failing with LDAP error 49, check if:
325
326    * /etc/dirsrv/keytab
327    * fedora-ds is able to read /etc/dirsrv/keytab
328    * /etc/hosts has not been modified by Network Manager (you
329      /did/ uninstall it, right? Right?)
330
331If the failure is local to a single master, usually you can recover
332by asking another master to refresh that master with:
333
334nsDS5BeginReplicaRefresh: start
335
336In practice, we've also had problems with this technique.  Some of them
337include:
338
339* Something like https://bugzilla.redhat.com/show_bug.cgi?id=547503
340  on Fedora 11 ns-slapd, where replication is turned off to do the
341  replication, but then it wedges and you need to forcibly kill the
342  process.
343
344* Failed LDAP authentication because another master attempted to do
345  an incremental update.
346
347* Repropagation of the error because the corrupt master thinks it still
348  should push updates.
349
350So the extremely safe method to bring up a crashed master is as follows:
351
3521. Disable all incoming and outgoing replication agreements by editing
353   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
354
355   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
356
357   and all of the push agreements.  Deleting them outright works, but
358   means you'll have to reconstruct all of the agreements from scratch.
359
3602. Bring up the server.
361
3623. Accept incoming replication data from a single server.
363
3644. Initiate a full update from that server.
365
3665. Finish setting up replication as described above.
367
368If your database gets extremely fucked, other servers may not be able
369to authenticate because your authentication information has gone missing.
370In that case, the minimal set of entries you need is:
371
372add dc=scripts,dc=mit,dc=edu
373objectClass: top
374objectClass: domain
375dc: scripts
376
377add ou=People,dc=scripts,dc=mit,dc=edu
378objectClass: top
379objectClass: organizationalunit
380ou: People
381
382add uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
383objectClass: account
384objectClass: top
385uid: ldap/whole-enchilada.mit.edu
Note: See TracBrowser for help on using the repository browser.