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

Last change on this file since 1698 was 1698, checked in by ezyang, 12 years ago
Restore r1692.
File size: 12.5 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 -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/dirsrv/slapd-scripts.socket
31nsslapd-ldapilisten: on
32nsslapd-syntaxcheck: off
34# Add these blocks
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)
48- Put LDAP keytab (ldap/ 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):
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
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
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
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
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
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
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
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
121- Build the indexes for all the fields:
123    /usr/lib64/dirsrv/slapd-scripts/ -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
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!)
129-  Watch for the indexing operations to finish with this command:
131    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
133  (look for nktaskstatus)
135- Set up replication.
137  We used to tell people to go execute
138 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.
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).
152  The procedure, at a high level, is this:
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.
159            M1 <---> M2 ---> S
161    2. Configure the new server to be replicated back.
163            M1 <---> M2 <---> S
165    3. Set up the rest of the replication agreements at your leisure.
167                M1 <---> M2
168                ^         ^
169                |         |
170                +--> S <--+
172  Here's how you do it.
174    1. Pull open the replication part of the database. It's fairly empty
175       right now.
177        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
179    2. Configure the server $SLAVE (this server) to accept $MASTER
180       replications by adding the following LDAP entries:
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/,ou=People,dc=scripts,dc=mit,dc=edu
190nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
191nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
192nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
193nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
194nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
195nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
196nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
197nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
198nsds5ReplicaPurgeDelay: 604800
199nsds5ReplicaLegacyConsumer: off
200nsDS5ReplicaType: 3
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.
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.
212add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
213uid: ldap/$MASTER
214objectClass: account
215objectClass: top
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.
221add cn=changelog5,cn=config
222objectclass: top
223objectclass: extensibleObject
224cn: changelog5
225nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
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.
231       The last line runs the replication.  This is perhaps the most
232       risky step of the process; see below for help debugging problems.
234       WARNING: There is a known bug doing full updates from 1.2.6 to
235       1.2.6, see
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
252    5. Check that the replication is running; the status will be stored
253    in the object we've been mucking around with.
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
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
263add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
264uid: ldap/$SLAVE
265objectClass: account
266objectClass: top
268    On $SLAVE,
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
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.
292LDAP multimaster replication can fail in a number of colorful ways;
293combine that with GSSAPI authentication and it goes exponential.
295If authentication is failing with LDAP error 49, check if:
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?)
302If the failure is local to a single master, usually you can recover
303by asking another master to refresh that master with:
305nsDS5BeginReplicaRefresh: start
307In practice, we've also had problems with this technique.  Some of them
310* Something like
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.
315* Failed LDAP authentication because another master attempted to do
316  an incremental update.
318* Repropagation of the error because the corrupt master thinks it still
319  should push updates.
321So the extremely safe method to bring up a crashed master is as follows:
3231. Disable all incoming and outgoing replication agreements by editing
324   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
326   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
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.
3312. Bring up the server.
3333. Accept incoming replication data from a single server.
3354. Initiate a full update from that server.
3375. Finish setting up replication as described above.
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:
343add dc=scripts,dc=mit,dc=edu
344objectClass: top
345objectClass: domain
346dc: scripts
348add ou=People,dc=scripts,dc=mit,dc=edu
349objectClass: top
350objectClass: organizationalunit
351ou: People
353add uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
354objectClass: account
355objectClass: top
356uid: ldap/
Note: See TracBrowser for help on using the repository browser.