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

Last change on this file since 2031 was 2016, checked in by ezyang, 13 years ago
Extra notes about LDAP.
File size: 14.4 KB
1To set up a new LDAP server:
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/
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]
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
34# We need to turn off syntax check because our schema is wrong and too
35# restrictive on some value. This should get fixed.
37# Add these blocks
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)
51- Put LDAP keytab (ldap/ 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):
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
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
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
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
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
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
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
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
124- Build the indexes for all the fields:
126    /usr/lib64/dirsrv/slapd-scripts/ -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
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!)
132-  Watch for the indexing operations to finish with this command:
134    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
136  (look for nktaskstatus)
138- Set up replication.
140  We used to tell people to go execute
141 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.
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).
155  The procedure, at a high level, is this:
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.
162            M1 <---> M2 ---> S
164    2. Configure the new server to be replicated back.
166            M1 <---> M2 <---> S
168    3. Set up the rest of the replication agreements.
170                M1 <---> M2
171                ^         ^
172                |         |
173                +--> S <--+
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.
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.
186  Here's how you do it.
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).
191    1. Pull open the replication part of the database. It's fairly empty
192       right now.
194        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
196    2. Configure the server $SLAVE (this server) to accept $MASTER
197       replications by adding the following LDAP entries:
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/,ou=People,dc=scripts,dc=mit,dc=edu
207nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
208nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
209nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
210nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
211nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
212nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
213nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
214nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
215nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
216nsds5ReplicaPurgeDelay: 604800
217nsds5ReplicaLegacyConsumer: off
218nsDS5ReplicaType: 3
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.
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.
230       REMEMBER: You need to use for the names!  Otherwise you will get
231       unauthorized errors.
233add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
234uid: ldap/$MASTER
235objectClass: account
236objectClass: top
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.
242add cn=changelog5,cn=config
243objectclass: top
244objectclass: extensibleObject
245cn: changelog5
246nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
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.
252       The last line runs the replication.  This is perhaps the most
253       risky step of the process; see below for help debugging problems.
255       WARNING: There is a known bug doing full updates from 1.2.6 to
256       1.2.6, see
258        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
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
275    5. Check that the replication is running; the status will be stored
276    in the object we've been mucking around with.
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.
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
287add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
288uid: ldap/$SLAVE
289objectClass: account
290objectClass: top
292    On $SLAVE,
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
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.
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).
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.
321    8. If at this point you look at the new server's changelog with
322    cl-dump (preferably /mit/scripts/admin/, 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.
332LDAP multimaster replication can fail in a number of colorful ways;
333combine that with GSSAPI authentication and it goes exponential.
335If authentication is failing with LDAP error 49, check if:
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?)
342If the failure is local to a single master, usually you can recover
343by asking another master to refresh that master with:
345nsDS5BeginReplicaRefresh: start
347In practice, we've also had problems with this technique.  Some of them
350* Something like
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.
355* Failed LDAP authentication because another master attempted to do
356  an incremental update.
358* Repropagation of the error because the corrupt master thinks it still
359  should push updates.
361So the extremely safe method to bring up a crashed master is as follows:
3631. Disable all incoming and outgoing replication agreements by editing
364   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
366   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
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.
3712. Bring up the server.
3733. Accept incoming replication data from a single server.
3754. Initiate a full update from that server.
3775. Finish setting up replication as described above.
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:
383add dc=scripts,dc=mit,dc=edu
384objectClass: top
385objectClass: domain
386dc: scripts
388add ou=People,dc=scripts,dc=mit,dc=edu
389objectClass: top
390objectClass: organizationalunit
391ou: People
393add uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
394objectClass: account
395objectClass: top
396uid: ldap/
Note: See TracBrowser for help on using the repository browser.