source: trunk/ldap/doc/install-ldap @ 2787

Last change on this file since 2787 was 2759, checked in by andersk, 7 years ago
Remove all remaining traces of apacheConfig records
File size: 14.0 KB
Line 
1# b
2# To set up a new LDAP server:
3
4# Temporarily move away the existing slapd-scripts folder
5mv /etc/dirsrv/slapd-scripts{,.bak}
6
7# Setup directory server
8/usr/sbin/setup-ds.pl
9#   - Choose a typical install
10#   - Tell it to use the fedora-ds user and group
11#   - Directory server identifier: scripts
12#   - Suffix: dc=scripts,dc=mit,dc=edu
13#   - Input directory manager password
14#     (this can be found in  ~/.ldapvirc)
15
16# Move the schema back
17cp -R /etc/dirsrv/slapd-scripts.bak/* /etc/dirsrv/slapd-scripts
18rm -Rf /etc/dirsrv/slapd-scripts.bak
19
20# Check and make sure the sysconfig references the correct keytab
21svn revert /etc/sysconfig/dirsrv-scripts
22
23# Turn dirsrv off:
24systemctl stop dirsrv@scripts.service
25
26# Apply the following configuration changes.  If you're editing
27# dse.ldif, you don't want dirsrv to be on, otherwise it will
28# overwrite your changes. [XXX: show how to do these changes with
29# dsconf, which is the "blessed" method, although it seems
30# dsconf only exists for Red Hat]
31
32vim /etc/dirsrv/slapd-scripts/dse.ldif
33<<<EOF
34
35# Inside cn=config.  These changes definitely require a restart.
36nsslapd-ldapilisten: on
37
38# Add these blocks
39
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)
51
52EOF;
53
54systemctl start dirsrv@scripts.service
55
56ldapvi -b cn=config
57# Add these indexes (6 of them):
58
59<<<EOF
60
61add cn=scriptsVhostName, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
62objectClass: top
63objectClass: nsIndex
64cn: scriptsVhostName
65nsSystemIndex: false
66nsIndexType: eq
67nsIndexType: pres
68
69add cn=scriptsVhostAlias, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
70objectClass: top
71objectClass: nsIndex
72cn: scriptsVhostAlias
73nsSystemIndex: false
74nsIndexType: eq
75nsIndexType: pres
76
77add cn=scriptsVhostAccount, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
78objectClass: top
79objectClass: nsIndex
80cn: scriptsVhostAccount
81nsSystemIndex: false
82nsIndexType: eq
83nsIndexType: pres
84
85add cn=memberuid, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
86objectClass: top
87objectClass: nsIndex
88cn: memberuid
89nsSystemIndex: false
90nsIndexType: eq
91nsIndexType: pres
92
93add cn=uidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
94objectClass: top
95objectClass: nsIndex
96cn: uidnumber
97nsSystemIndex: false
98nsIndexType: eq
99nsIndexType: pres
100
101add cn=gidnumber, cn=index, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
102objectClass: top
103objectClass: nsIndex
104cn: gidnumber
105nsSystemIndex: false
106nsIndexType: eq
107nsIndexType: pres
108
109EOF;
110
111- Build the indexes for all the fields:
112
113    /usr/lib64/dirsrv/slapd-scripts/db2index.pl -D "cn=Directory Manager" -j /etc/signup-ldap-pw -n userRoot
114
115  (/etc/signup-ldap-pw is the LDAP root password, make sure it's
116  chmodded correctly and chowned to signup. Also, make sure it doesn't
117  have a trailing newline!)
118
119-  Watch for the indexing operations to finish with this command:
120
121    ldapsearch -x -y /etc/signup-ldap-pw -D 'cn=Directory Manager' -b cn=tasks,cn=config
122
123  (look for nktaskstatus)
124
125- Set up replication.
126
127  We used to tell people to go execute
128  http://directory.fedoraproject.org/sources/contrib/mmr.pl manually
129  (manually because that script assumes only two masters and we have
130  every one of our servers set up as a master.)  However, those
131  instructions are inaccurate, because we use GSSAPI, not SSL and
132  because the initializing procedure is actually prone to a race
133  condition.  Here are some better instructions.
134
135  LDAP replication is based around producers and consumers.  Producers
136  push changes in LDAP to consumers: these arrangements are called
137  "replication agreements" and the producer will hold a
138  nsDS5ReplicationAgreement object that represents this commitment,
139  as well as some extra configuration to say who consumers will accept
140  replication data from (a nsDS5Replica).
141
142  The procedure, at a high level, is this:
143
144    1. Pick an arbitrary existing master.  The current server will
145       be configured as a slave to that master.  Initialize a changelog,
146       then request a replication to populate our server with
147       information.
148
149            M1 <---> M2 ---> S
150
151    2. Configure the new server to be replicated back.
152
153            M1 <---> M2 <---> S
154
155    3. Set up the rest of the replication agreements.
156
157                M1 <---> M2
158                ^         ^
159                |         |
160                +--> S <--+
161
162    4. Push a change from every existing server (to the new server), and
163       then a change from the new server to (all) the existing servers.
164       In addition to merely testing that replication works, this will
165       set up the servers' changelogs properly.
166
167       If this step is not completed before any server's LDAP server
168       shuts down, then the replication agreements will fall apart the
169       next time a change is made. You may wish to intentionally reboot
170       any servers that look like they want to crash _before_ beginning
171       this process.
172
173  Here's how you do it.
174
175  NOTE: There's this spiffy new tool MMR hammer which automates some of
176  this process.  Check the "MMR Hammer" sections to see how.  Install it
177  here:  https://github.com/ezyang/mmr-hammer
178
179    0. Tell -c scripts not to go off and reboot servers until you're
180       done (or to get any rebooting done with first).
181
182    1. Pull open the replication part of the database. It's fairly empty
183       right now.
184
185        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
186
187    2. Configure the server $SLAVE (this server) to accept $MASTER
188       replications by adding the following LDAP entries:
189
190add cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
191objectClass: top
192objectClass: nsDS5Replica
193cn: replica
194nsDS5ReplicaId: $REPLICA_ID
195nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
196nsDS5Flags: 1
197nsDS5ReplicaBindDN: uid=ldap/bees-knees.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
198nsDS5ReplicaBindDN: uid=ldap/busy-beaver.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
199nsDS5ReplicaBindDN: uid=ldap/cats-whiskers.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
200nsDS5ReplicaBindDN: uid=ldap/pancake-bunny.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
201nsDS5ReplicaBindDN: uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
202nsDS5ReplicaBindDN: uid=ldap/real-mccoy.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
203nsDS5ReplicaBindDN: uid=ldap/better-mousetrap.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
204nsDS5ReplicaBindDN: uid=ldap/old-faithful.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
205nsDS5ReplicaBindDN: uid=ldap/shining-armor.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
206nsDS5ReplicaBindDN: uid=ldap/golden-egg.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
207nsDS5ReplicaBindDN: uid=ldap/miracle-cure.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
208nsDS5ReplicaBindDN: uid=ldap/lucky-star.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
209nsds5ReplicaPurgeDelay: 604800
210nsds5ReplicaLegacyConsumer: off
211nsDS5ReplicaType: 3
212
213        $REPLICA_ID is the scripts$N number (stella $HOSTNAME to find
214        out.)  You might wonder why we are binding to all servers;
215        weren't we going to replicate from only one server?  That is
216        correct, however, simply binding won't mean we will receive
217        updates; we have to setup the $MASTER to send data $SLAVE.
218
219    3. Although we allowed those uids to bind, that user information
220       doesn't exist on $SLAVE yet.  So you'll need to create the entry
221       for just $MASTER.
222
223       REMEMBER: You need to use FOO.mit.edu for the names!  Otherwise you will get
224       unauthorized errors.
225
226add uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
227uid: ldap/$MASTER
228objectClass: account
229objectClass: top
230
231    4. Though our $SLAVE will not be making changes to LDAP, we need to
232       initialize the changelog because we intend to be able to do this
233       later.
234
235add cn=changelog5,cn=config
236objectclass: top
237objectclass: extensibleObject
238cn: changelog5
239nsslapd-changelogdir: /etc/dirsrv/slapd-scripts/changelogdb
240
241    5. Ok, now go to your $MASTER server that you picked (it should have
242       been one of the hosts mentioned in nsDS5ReplicaBindDN) and tell
243       it to replicate to $SLAVE.
244
245       The last line runs the replication.  This is perhaps the most
246       risky step of the process; see below for help debugging problems.
247
248       MMR Hammer:
249        mmr-hammer -h $MASTER init agreements $SLAVE
250        mmr-hammer -h $MASTER update $SLAVE # XXX pick a better name
251
252        ldapvi -b cn=\"dc=scripts,dc=mit,dc=edu\",cn=mapping\ tree,cn=config
253
254add cn="GSSAPI Replication to $SLAVE", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
255objectClass: top
256objectClass: nsDS5ReplicationAgreement
257cn: "GSSAPI Replication to $SLAVE"
258cn: GSSAPI Replication to $SLAVE
259nsDS5ReplicaHost: $SLAVE
260nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
261nsDS5ReplicaPort: 389
262nsDS5ReplicaTransportInfo: LDAP
263nsDS5ReplicaBindDN: uid=ldap/$MASTER,ou=People,dc=scripts,dc=mit,dc=edu
264nsDS5ReplicaBindMethod: SASL/GSSAPI
265nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
266nsDS5ReplicaTimeout: 120
267nsDS5BeginReplicaRefresh: start
268
269    5. Check that the replication is running; the status will be stored
270    in the object we've been mucking around with.
271
272    If it fails with LDAP Error 49, check /var/log/dirsrv on $MASTER
273    for more information.  It might be because fedora-ds can't read
274    /etc/dirsrv/keytab or because you setup the account on the SLAVE
275    incorrectly.
276
277    6. Replicate in the other direction.  On $MASTER, add $SLAVE
278    as a nsDS5ReplicaBindDN in cn=replica,cn="dc=scripts,dc=mit,dc=edu",cn=mapping tree,cn=config
279    Also, add an account for $SLAVE if it doesn't exist already.
280
281add uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
282uid: ldap/$SLAVE
283objectClass: account
284objectClass: top
285
286    On $SLAVE,
287
288       MMR Hammer: mmr-hammer -h $SLAVE init agreements $MASTER
289
290add cn="GSSAPI Replication to $MASTER", cn=replica, cn="dc=scripts,dc=mit,dc=edu", cn=mapping tree, cn=config
291objectClass: top
292objectClass: nsDS5ReplicationAgreement
293cn: "GSSAPI Replication to $MASTER"
294cn: GSSAPI Replication to $MASTER
295nsDS5ReplicaHost: $MASTER
296nsDS5ReplicaRoot: dc=scripts,dc=mit,dc=edu
297nsDS5ReplicaPort: 389
298nsDS5ReplicaTransportInfo: LDAP
299nsDS5ReplicaBindDN: uid=ldap/$SLAVE,ou=People,dc=scripts,dc=mit,dc=edu
300nsDS5ReplicaBindMethod: SASL/GSSAPI
301nsDS5ReplicaUpdateSchedule: "0000-2359 0123456"
302nsDS5ReplicaTimeout: 120
303
304    If you get a really scary internal server error, that might mean you
305    forgot to initialize the changelog.  Remove the replication
306    agreement (you'll need to turn off dirsrv), add the changelog, and
307    then try again.
308
309    7. Repeat step 6 to complete the graph of replications (i.e., from
310    every other server to the new server, and from the new server to
311    every other server).
312
313    Note the only difference between steps 5 and 6 is the lack of
314    nsDS5ReplicaRefresh: start. That only needs to be done once, to the
315    new server.
316
317    With MMR hammer, that's something like:
318
319        for i in $SERVER_NAMES; do mmr-hammer -h $i init agreements $SERVER_NAMES; done
320
321    8. If at this point you look at the new server's changelog with
322    cl-dump (preferably /mit/scripts/admin/cl-dump.pl, 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.
328
329    With MMR hammer, that's something like:
330
331        for i in $SERVER_NAMES; do mmr-hammer -h $i test; sleep 20; done
332
333Troubleshooting
334===============
335
336LDAP multimaster replication can fail in a number of colorful ways;
337combine that with GSSAPI authentication and it goes exponential.
338
339If authentication is failing with LDAP error 49, check if:
340
341    * /etc/dirsrv/keytab
342    * fedora-ds is able to read /etc/dirsrv/keytab
343    * /etc/hosts has not been modified by Network Manager (you
344      /did/ uninstall it, right? Right?)
345
346If the failure is local to a single master, usually you can recover
347by asking another master to refresh that master with:
348
349nsDS5BeginReplicaRefresh: start
350
351In practice, we've also had problems with this technique.  Some of them
352include:
353
354* Something like https://bugzilla.redhat.com/show_bug.cgi?id=547503
355  on Fedora 11 ns-slapd, where replication is turned off to do the
356  replication, but then it wedges and you need to forcibly kill the
357  process.
358
359* Failed LDAP authentication because another master attempted to do
360  an incremental update.
361
362* Repropagation of the error because the corrupt master thinks it still
363  should push updates.
364
365So the extremely safe method to bring up a crashed master is as follows:
366
3671. Disable all incoming and outgoing replication agreements by editing
368   /etc/dirsrv/slapd-scripts/dse.ldif. You'll need to munge:
369
370   nsDS5ReplicaBindDN in cn=replica,cn=dc\3Dscripts\2Cdc\3Dmit\2Cdc\3Dedu,cn=mapping tree,cn=config
371
372   and all of the push agreements.  Deleting them outright works, but
373   means you'll have to reconstruct all of the agreements from scratch.
374
3752. Bring up the server.
376
3773. Accept incoming replication data from a single server.
378
3794. Initiate a full update from that server.
380
3815. Finish setting up replication as described above.
382
383If your database gets extremely fucked, other servers may not be able
384to authenticate because your authentication information has gone missing.
385In that case, the minimal set of entries you need is:
386
387add dc=scripts,dc=mit,dc=edu
388objectClass: top
389objectClass: domain
390dc: scripts
391
392add ou=People,dc=scripts,dc=mit,dc=edu
393objectClass: top
394objectClass: organizationalunit
395ou: People
396
397add uid=ldap/whole-enchilada.mit.edu,ou=People,dc=scripts,dc=mit,dc=edu
398objectClass: account
399objectClass: top
400uid: ldap/whole-enchilada.mit.edu
Note: See TracBrowser for help on using the repository browser.