source: branches/fc13-dev/server/doc/install-ldap @ 2553

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