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

Last change on this file since 1966 was 1878, checked in by achernya, 13 years ago
Merge r1803-1877 from trunk to branches/fc15-dev
File size: 12.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 -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
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- /sbin/service dirsrv start
54- Use ldapvi -b cn=config to add these indexes (8 of them):
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
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
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
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
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
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
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
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
120- Build the indexes for all the fields:
122    /usr/lib64/dirsrv/slapd-scripts/ -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
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!)
128-  Watch for the indexing operations to finish with this command:
130    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
132  (look for nktaskstatus)
134- Set up replication.
136  We used to tell people to go execute
137 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.
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).
151  The procedure, at a high level, is this:
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.
158            M1 <---> M2 ---> S
160    2. Configure the new server to be replicated back.
162            M1 <---> M2 <---> S
164    3. Set up the rest of the replication agreements at your leisure.
166                M1 <---> M2
167                ^         ^
168                |         |
169                +--> S <--+
171  Here's how you do it.
173    1. Pull open the replication part of the database. It's fairly empty
174       right now.
176        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
178    2. Configure the server $SLAVE (this server) to accept $MASTER
179       replications by adding the following LDAP entries:
181add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
182objectClass: top
183objectClass: nsDS5Replica
184cn: replica
185nsDS5ReplicaId: $REPLICA_ID
186nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
187nsDS5Flags: 1
188nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
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
197nsds5ReplicaPurgeDelay: 604800
198nsds5ReplicaLegacyConsumer: off
199nsDS5ReplicaType: 3
201        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
202        out.)  You might wonder why we are binding to all servers;
203        weren't we going to replicate from only one server?  That is
204        correct, however, simply binding won't mean we will receive
205        updates; we have to setup the $MASTER to send data $SLAVE.
207    3. Although we allowed those uids to bind, that user information
208       doesn't exist on $SLAVE yet.  So you'll need to create the entry
209       for just $MASTER.
211add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
212uid: ldap/$MASTER
213objectClass: account
214objectClass: top
216    4. Though our $SLAVE will not be making changes to LDAP, we need to
217       initialize the changelog because we intend to be able to do this
218       later.
220add cn=changelog5,cn=config
221objectclass: top
222objectclass: extensibleObject
223cn: changelog5
224nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
226    5. Ok, now go to your $MASTER server that you picked (it should have
227       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
228       it to replicate to $SLAVE.
230       The last line runs the replication.  This is perhaps the most
231       risky step of the process; see below for help debugging problems.
233       WARNING: There is a known bug doing full updates from 1.2.6 to
234       1.2.6, see
236add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
237objectClass: top
238objectClass: nsDS5ReplicationAgreement
239cn: "GSSAPI Replication to $SLAVE"
240cn: GSSAPI Replication to $SLAVE
241nsDS5ReplicaHost: $SLAVE
242nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
243nsDS5ReplicaPort: 389
244nsDS5ReplicaTransportInfo: LDAP
245nsDS5ReplicaBindDN: uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
246nsDS5ReplicaBindMethod: SASL/GSSAPI
247nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
248nsDS5ReplicaTimeout: 120
249nsDS5BeginReplicaRefresh: start
251    5. Check that the replication is running; the status will be stored
252    in the object we've been mucking around with.
254    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
255    for more information.  It might be because fedora-ds can't read
256    /etc/dirsrv/keytab
258    6. Replicate in the other direction.  On $MASTER, add $SLAVE
259    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
260    Also, add an account for $SLAVE
262add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
263uid: ldap/$SLAVE
264objectClass: account
265objectClass: top
267    On $SLAVE,
269add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
270objectClass: top
271objectClass: nsDS5ReplicationAgreement
272cn: "GSSAPI Replication to $MASTER"
273cn: GSSAPI Replication to $MASTER
274nsDS5ReplicaHost: $MASTER
275nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
276nsDS5ReplicaPort: 389
277nsDS5ReplicaTransportInfo: LDAP
278nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
279nsDS5ReplicaBindMethod: SASL/GSSAPI
280nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
281nsDS5ReplicaTimeout: 120
283    If you get a really scary internal server error, that might mean you
284    forgot to initialize the changelog.  Remove the replication
285    agreement (you'll need to turn off dirsrv), add the changelog, and
286    then try again.
291LDAP multimaster replication can fail in a number of colorful ways;
292combine that with GSSAPI authentication and it goes exponential.
294If authentication is failing with LDAP error 49, check if:
296    * /etc/dirsrv/keytab
297    * fedora-ds is able to read /etc/dirsrv/keytab
298    * /etc/hosts has not been modified by Network Manager (you
299      /did/ uninstall it, right? Right?)
301If the failure is local to a single master, usually you can recover
302by asking another master to refresh that master with:
304nsDS5BeginReplicaRefresh: start
306In practice, we've also had problems with this technique.  Some of them
309* Something like
310  on Fedora 11 ns-slapd, where replication is turned off to do the
311  replication, but then it wedges and you need to forcibly kill the
312  process.
314* Failed LDAP authentication because another master attempted to do
315  an incremental update.
317* Repropagation of the error because the corrupt master thinks it still
318  should push updates.
320So the extremely safe method to bring up a crashed master is as follows:
3221. Disable all incoming and outgoing replication agreements by editing
323   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
325   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
327   and all of the push agreements.  Deleting them outright works, but
328   means you'll have to reconstruct all of the agreements from scratch.
3302. Bring up the server.
3323. Accept incoming replication data from a single server.
3344. Initiate a full update from that server.
3365. Finish setting up replication as described above.
338If your database gets extremely fucked, other servers may not be able
339to authenticate because your authentication information has gone missing.
340In that case, the minimal set of entries you need is:
342add dc=scripts,dc=mit,dc=edu
343objectClass: top
344objectClass: domain
345dc: scripts
347add ou=People,dc=scripts,dc=mit,dc=edu
348objectClass: top
349objectClass: organizationalunit
350ou: People
352add uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
353objectClass: account
354objectClass: top
355uid: ldap/
Note: See TracBrowser for help on using the repository browser.