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

Last change on this file since 2066 was 2066, checked in by achernya, 11 years ago
Merge branches/fc15-dev to trunk
File size: 14.2 KB
[2066]1# To set up a new LDAP server:
[2066]3# Temporarily move away the existing slapd-scripts folder
4mv /etc/dirsrv/slapd-scripts{,.bak}
[2066]6# Setup directory server
8#   - Choose a typical install
9#   - Tell it to use the fedora-ds user and group
10#   - Directory server identifier: scripts
11#   - Suffix: dc=scripts,dc=mit,dc=edu
12#   - Input directory manager password
13#     (this can be found in  ~/.ldapvirc)
15# Move the schema back
16cp -R /etc/dirsrv/slapd-scripts.bak/{.svn,*} /etc/dirsrv/slapd-scripts
17rm -Rf /etc/dirsrv/slapd-scripts.bak
19# Turn dirsrv off:
20systemctl stop dirsrv.service
22# Apply the following configuration changes.  If you're editing
23# dse.ldif, you don't want dirsrv to be on, otherwise it will
24# overwrite your changes. [XXX: show how to do these changes with
25# dsconf, which is the "blessed" method, although it seems
26# dsconf only exists for Red Hat]
28vim /etc/dirsrv/slapd-scripts/dse.ldif
[1645]31# Inside cn=config.  These changes definitely require a restart.
32nsslapd-ldapilisten: on
[1698]33nsslapd-syntaxcheck: off
[2066]35# We need to turn off syntax check because our schema is wrong and too
36# restrictive on some value. This should get fixed.
[1645]38# Add these blocks
40# mapname, mapping, sasl, config
41# This is the most liberal mapping you can have for SASL: you can
42# basically add authentication for any given GSSAPI mechanism by
43# explicitly creating the UID for that SASL string.
44dn: cn=mapname,cn=mapping,cn=sasl,cn=config
45objectClass: top
46objectClass: nsSaslMapping
47cn: mapname
48nsSaslMapRegexString: \(.*\)
49nsSaslMapBaseDNTemplate: uid=\1,ou=People,dc=scripts,dc=mit,dc=edu
50nsSaslMapFilterTemplate: (objectClass=posixAccount)
[2066]54systemctl start dirsrv.service
56ldapvi -b cn=config
57# Add these indexes (8 of them):
[880]61add cn=apacheServerName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
62objectClass: top
63objectClass: nsIndex
64cn: apacheServerName
65nsSystemIndex: false
66nsIndexType: eq
67nsIndexType: pres
69add cn=apacheServerAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
70objectClass: top
71objectClass: nsIndex
72cn: apacheServerAlias
73nsSystemIndex: false
74nsIndexType: eq
75nsIndexType: pres
[1473]77add cn=scriptsVhostName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
78objectClass: top
79objectClass: nsIndex
80cn: scriptsVhostName
81nsSystemIndex: false
82nsIndexType: eq
83nsIndexType: pres
[1473]85add cn=scriptsVhostAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
86objectClass: top
87objectClass: nsIndex
88cn: scriptsVhostAlias
89nsSystemIndex: false
90nsIndexType: eq
91nsIndexType: pres
[1532]93add cn=scriptsVhostAccount, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
94objectClass: top
95objectClass: nsIndex
96cn: scriptsVhostAccount
97nsSystemIndex: false
98nsIndexType: eq
99nsIndexType: pres
[1473]101add cn=memberuid, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
102objectClass: top
103objectClass: nsIndex
104cn: memberuid
105nsSystemIndex: false
106nsIndexType: eq
107nsIndexType: pres
109add cn=uidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
110objectClass: top
111objectClass: nsIndex
112cn: uidnumber
113nsSystemIndex: false
114nsIndexType: eq
115nsIndexType: pres
117add cn=gidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
118objectClass: top
119objectClass: nsIndex
120cn: gidnumber
121nsSystemIndex: false
122nsIndexType: eq
123nsIndexType: pres
[1473]127- Build the indexes for all the fields:
129    /usr/lib64/dirsrv/slapd-scripts/ -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
[1645]131  (/etc/signup-ldap-pw is the LDAP root password, make sure it's
132  chmodded correctly and chowned to signup. Also, make sure it doesn't
133  have a trailing newline!)
[1473]135-  Watch for the indexing operations to finish with this command:
137    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
[1645]139  (look for nktaskstatus)
141- Set up replication.
143  We used to tell people to go execute
144 manually
145  (manually because that script assumes only two masters and we have
146  every one of our servers set up as a master.)  However, those
147  instructions are inaccurate, because we use GSSAPI, not SSL and
148  because the initializing procedure is actually prone to a race
149  condition.  Here are some better instructions.
151  LDAP replication is based around producers and consumers.  Producers
152  push changes in LDAP to consumers: these arrangements are called
153  "replication agreements" and the producer will hold a
154  nsDS5ReplicationAgreement object that represents this commitment,
155  as well as some extra configuration to say who consumers will accept
156  replication data from (a nsDS5Replica).
158  The procedure, at a high level, is this:
160    1. Pick an arbitrary existing master.  The current server will
161       be configured as a slave to that master.  Initialize a changelog,
162       then request a replication to populate our server with
163       information.
165            M1 <---> M2 ---> S
167    2. Configure the new server to be replicated back.
169            M1 <---> M2 <---> S
[1983]171    3. Set up the rest of the replication agreements.
173                M1 <---> M2
174                ^         ^
175                |         |
176                +--> S <--+
[1983]178    4. Push a change from every existing server (to the new server), and
179       then a change from the new server to (all) the existing servers.
180       In addition to merely testing that replication works, this will
181       set up the servers' changelogs properly.
[1986]183       If this step is not completed before any server's LDAP server
184       shuts down, then the replication agreements will fall apart the
185       next time a change is made. You may wish to intentionally reboot
186       any servers that look like they want to crash _before_ beginning
187       this process.
[1645]189  Here's how you do it.
[2066]191  NOTE: There's this spiffy new tool MMR hammer which automates some of
192  this process.  Check the "MMR Hammer" sections to see how.  Install it
193  here:
[1986]195    0. Tell -c scripts not to go off and reboot servers until you're
196       done (or to get any rebooting done with first).
[1645]198    1. Pull open the replication part of the database. It's fairly empty
199       right now.
[1680]201        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
203    2. Configure the server $SLAVE (this server) to accept $MASTER
204       replications by adding the following LDAP entries:
206add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
207objectClass: top
208objectClass: nsDS5Replica
209cn: replica
210nsDS5ReplicaId: $REPLICA_ID
211nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
212nsDS5Flags: 1
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
216nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
217nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
218nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
[1677]219nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
220nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
[1698]221nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
[2066]222nsDS5ReplicaBindDN: uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
[1645]223nsds5ReplicaPurgeDelay: 604800
224nsds5ReplicaLegacyConsumer: off
225nsDS5ReplicaType: 3
227        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
228        out.)  You might wonder why we are binding to all servers;
229        weren't we going to replicate from only one server?  That is
230        correct, however, simply binding won't mean we will receive
[1677]231        updates; we have to setup the $MASTER to send data $SLAVE.
233    3. Although we allowed those uids to bind, that user information
234       doesn't exist on $SLAVE yet.  So you'll need to create the entry
235       for just $MASTER.
[2066]237       REMEMBER: You need to use for the names!  Otherwise you will get
238       unauthorized errors.
[1645]240add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
241uid: ldap/$MASTER
242objectClass: account
243objectClass: top
245    4. Though our $SLAVE will not be making changes to LDAP, we need to
246       initialize the changelog because we intend to be able to do this
247       later.
249add cn=changelog5,cn=config
250objectclass: top
251objectclass: extensibleObject
252cn: changelog5
253nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
255    5. Ok, now go to your $MASTER server that you picked (it should have
256       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
257       it to replicate to $SLAVE.
[1680]259       The last line runs the replication.  This is perhaps the most
260       risky step of the process; see below for help debugging problems.
[2066]262       MMR Hammer: mmr-hammer -h $MASTER init agreements $SLAVE
[2066]264        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
[1645]266add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
267objectClass: top
268objectClass: nsDS5ReplicationAgreement
269cn: "GSSAPI Replication to $SLAVE"
270cn: GSSAPI Replication to $SLAVE
271nsDS5ReplicaHost: $SLAVE
272nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
273nsDS5ReplicaPort: 389
274nsDS5ReplicaTransportInfo: LDAP
[1680]275nsDS5ReplicaBindDN: uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
[1645]276nsDS5ReplicaBindMethod: SASL/GSSAPI
277nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
278nsDS5ReplicaTimeout: 120
279nsDS5BeginReplicaRefresh: start
281    5. Check that the replication is running; the status will be stored
282    in the object we've been mucking around with.
284    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
285    for more information.  It might be because fedora-ds can't read
[2066]286    /etc/dirsrv/keytab or because you setup the account on the SLAVE
287    incorrectly.
289    6. Replicate in the other direction.  On $MASTER, add $SLAVE
290    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
[2066]291    Also, add an account for $SLAVE if it doesn't exist already.
293add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
294uid: ldap/$SLAVE
295objectClass: account
296objectClass: top
298    On $SLAVE,
[2066]300       MMR Hammer: mmr-hammer -h $SLAVE init agreements $MASTER
[1645]302add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
303objectClass: top
304objectClass: nsDS5ReplicationAgreement
305cn: "GSSAPI Replication to $MASTER"
306cn: GSSAPI Replication to $MASTER
307nsDS5ReplicaHost: $MASTER
308nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
309nsDS5ReplicaPort: 389
310nsDS5ReplicaTransportInfo: LDAP
311nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
312nsDS5ReplicaBindMethod: SASL/GSSAPI
313nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
314nsDS5ReplicaTimeout: 120
316    If you get a really scary internal server error, that might mean you
317    forgot to initialize the changelog.  Remove the replication
318    agreement (you'll need to turn off dirsrv), add the changelog, and
319    then try again.
[1983]321    7. Repeat step 6 to complete the graph of replications (i.e., from
322    every other server to the new server, and from the new server to
323    every other server).
325    Note the only difference between steps 5 and 6 is the lack of
326    nsDS5ReplicaRefresh: start. That only needs to be done once, to the
327    new server.
[2066]329    With MMR hammer, that's something like:
331        for i in $SERVER_NAMES; do mmr-hammer -h $i init agreements $SERVER_NAMES; done
[1983]333    8. If at this point you look at the new server's changelog with
334    cl-dump (preferably /mit/scripts/admin/, to not prompt you
335    for a password), you won't see the servers you added in step 7. So,
336    from each of those servers, make a change to some record so it gets
337    propagated to the new server, and then one from the new server so it
338    gets propagated to all the existing servers' changelogs. This is
339    also good for making sure the replication agreements actually work.
[2066]341    With MMR hammer, that's something like:
343        for i in $SERVER_NAMES; do mmr-hammer -h $i test; sleep 20; done
[1677]348LDAP multimaster replication can fail in a number of colorful ways;
349combine that with GSSAPI authentication and it goes exponential.
351If authentication is failing with LDAP error 49, check if:
353    * /etc/dirsrv/keytab
354    * fedora-ds is able to read /etc/dirsrv/keytab
355    * /etc/hosts has not been modified by Network Manager (you
356      /did/ uninstall it, right? Right?)
[1672]358If the failure is local to a single master, usually you can recover
359by asking another master to refresh that master with:
361nsDS5BeginReplicaRefresh: start
363In practice, we've also had problems with this technique.  Some of them
366* Something like
367  on Fedora 11 ns-slapd, where replication is turned off to do the
368  replication, but then it wedges and you need to forcibly kill the
369  process.
371* Failed LDAP authentication because another master attempted to do
372  an incremental update.
374* Repropagation of the error because the corrupt master thinks it still
375  should push updates.
377So the extremely safe method to bring up a crashed master is as follows:
3791. Disable all incoming and outgoing replication agreements by editing
380   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
382   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
384   and all of the push agreements.  Deleting them outright works, but
385   means you'll have to reconstruct all of the agreements from scratch.
3872. Bring up the server.
3893. Accept incoming replication data from a single server.
3914. Initiate a full update from that server.
3935. Finish setting up replication as described above.
395If your database gets extremely fucked, other servers may not be able
396to authenticate because your authentication information has gone missing.
397In that case, the minimal set of entries you need is:
399add dc=scripts,dc=mit,dc=edu
400objectClass: top
401objectClass: domain
402dc: scripts
404add ou=People,dc=scripts,dc=mit,dc=edu
405objectClass: top
406objectClass: organizationalunit
407ou: People
[1677]409add uid=ldap/,ou=People,dc=scripts,dc=mit,dc=edu
[1672]410objectClass: account
411objectClass: top
[1677]412uid: ldap/
Note: See TracBrowser for help on using the repository browser.