]> git.sur5r.net Git - openldap/blob - doc/guide/admin/tuning.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / tuning.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Tuning
6
7 This is perhaps one of the most important chapters in the guide, because if 
8 you have not tuned {{slapd}}(8) correctly or grasped how to design your
9 directory and environment, you can expect very poor performance.
10
11 Reading, understanding and experimenting using the instructions and information
12 in the following sections, will enable you to fully understand how to tailor 
13 your directory server to your specific requirements.
14
15 It should be noted that the following information has been collected over time
16 from our community based FAQ. So obviously the benefit of this real world experience
17 and advice should be of great value to the reader.
18
19
20 H2: Performance Factors
21
22 Various factors can play a part in how your directory performs on your chosen 
23 hardware and environment. We will attempt to discuss these here.
24
25
26 H3: Memory
27
28 Scale your cache to use available memory and increase system memory if you can.
29
30 See {{SECT:Caching}}
31
32
33 H3: Disks
34
35 Use fast subsystems. Put each database and logs on separate disks configurable
36 via {{DB_CONFIG}}:
37
38 >       # Data Directory
39 >       set_data_dir /data/db
40 >       
41 >       # Transaction Log settings
42 >       set_lg_dir /logs
43
44
45 H3: Network Topology
46
47 http://www.openldap.org/faq/data/cache/363.html
48
49 Drawing here.
50
51
52 H3: Directory Layout Design
53
54 Reference to other sections and good/bad drawing here.
55
56
57 H3: Expected Usage
58
59 Discussion.
60
61
62 H2: Indexes
63
64 H3: Understanding how a search works
65
66 If you're searching on a filter that has been indexed, then the search reads 
67 the index and pulls exactly the entries that are referenced by the index. 
68 If the filter term has not been indexed, then the search must read every single
69  entry in the target scope and test to see if each entry matches the filter. 
70 Obviously indexing can save a lot of work when it's used correctly.
71
72 H3: What to index
73
74 You should create indices to match the actual filter terms used in
75 search queries. 
76
77 >        index cn,sn,givenname,mail eq
78
79 Each attribute index can be tuned further by selecting the set of index types to generate. For example, substring and approximate search for organizations (o) may make little sense (and isn't like done very often). And searching for {{userPassword}} likely makes no sense what so ever.
80
81 General rule: don't go overboard with indexes. Unused indexes must be maintained and hence can only slow things down. 
82
83 See {{slapd.conf}}(8) and {{slapdindex}}(8) for more information
84
85
86 H3: Presence indexing
87
88 If your client application uses presence filters and if the
89 target attribute exists on the majority of entries in your target scope, then
90 all of those entries are going to be read anyway, because they are valid
91 members of the result set. In a subtree where 100% of the
92 entries are going to contain the same attributes, the presence index does
93 absolutely NOTHING to benefit the search, because 100% of the entries match
94 that presence filter. 
95
96 So the resource cost of generating the index is a
97 complete waste of CPU time, disk, and memory. Don't do it unless you know
98 that it will be used, and that the attribute in question occurs very
99 infrequently in the target data. 
100
101 Almost no applications use presence filters in their search queries. Presence
102 indexing is pointless when the target attribute exists on the majority of
103 entries in the database. In most LDAP deployments, presence indexing should
104 not be done, it's just wasted overhead.
105
106 See the {{Logging}} section below on what to watch our for if you have a frequently searched
107 for attribute that is unindexed.
108
109
110 H2: Logging
111
112 H3: What log level to use
113
114 The default of {{loglevel stats}} (256) is really the best bet. There's a corollary to 
115 this when problems *do* arise, don't try to trace them using syslog. 
116 Use the debug flag instead, and capture slapd's stderr output. syslog is too 
117 slow for debug tracing, and it's inherently lossy - it will throw away messages when it
118 can't keep up.
119
120 Contrary to popular belief, {{loglevel 0}} is not ideal for production as you 
121 won't be able to track when problems first arise.
122
123 H3: What to watch out for
124
125 The most common message you'll see that you should pay attention to is:
126
127 >       "<= bdb_equality_candidates: (foo) index_param failed (18)"
128
129 That means that some application tried to use an equality filter ({{foo=<somevalue>}}) 
130 and attribute {{foo}} does not have an equality index. If you see a lot of these
131 messages, you should add the index. If you see one every month or so, it may
132 be acceptable to ignore it.
133
134 The default syslog level is stats (256) which logs the basic parameters of each
135 request; it usually produces 1-3 lines of output. On Solaris and systems that
136 only provide synchronous syslog, you may want to turn it off completely, but
137 usually you want to leave it enabled so that you'll be able to see index
138 messages whenever they arise. On Linux you can configure syslogd to run
139 asynchronously, in which case the performance hit for moderate syslog traffic
140 pretty much disappears.
141
142 H3: Improving throughput
143
144 You can improve logging performance on some systems by configuring syslog not 
145 to sync the file system with every write ({{man syslogd/syslog.conf}}). In Linux, 
146 you can prepend the log file name with a "-" in {{syslog.conf}}. For example, 
147 if you are using the default LOCAL4 logging you could try:
148
149 >       # LDAP logs
150 >       LOCAL4.*         -/var/log/ldap
151
152 For syslog-ng, add or modify the following line in {{syslog-ng.conf}}:
153
154 >       options { sync(n); };
155
156 where n is the number of lines which will be buffered before a write.
157
158
159 H2: Caching
160
161 We all know what caching is, don't we? 
162
163 In brief, "A cache is a block of memory for temporary storage of data likely 
164 to be used again" - {{URL:http://en.wikipedia.org/wiki/Cache}}
165
166 There are 3 types of caches, BerkeleyDB's own cache, {{slapd}}(8) 
167 entry cache and {{TERM:IDL}} (IDL) cache.
168
169
170 H3: Berkeley DB Cache
171
172 There are two ways to tune for the BDB cachesize:
173
174 (a) BDB cache size necessary to load the database via slapadd in optimal time
175
176 (b) BDB cache size necessary to have a high performing running slapd once the data is loaded
177
178 For (a), the optimal cachesize is the size of the entire database.  If you 
179 already have the database loaded, this is simply a 
180
181 >       du -c -h *.bdb 
182
183 in the directory containing the OpenLDAP ({{/usr/local/var/openldap-data}}) data.
184
185 For (b), the optimal cachesize is just the size of the {{id2entry.bdb}} file, 
186 plus about 10% for growth.
187
188 The tuning of {{DB_CONFIG}} should be done for each BDB type database 
189 instantiated (back-bdb, back-hdb).
190
191 Note that while the {{TERM:BDB}} cache is just raw chunks of memory and 
192 configured as a memory size, the {{slapd}}(8) entry cache holds parsed entries, 
193 and the size of each entry is variable. 
194
195 There is also an IDL cache which is used for Index Data Lookups. 
196 If you can fit all of your database into slapd's entry cache, and all of your 
197 index lookups fit in the IDL cache, that will provide the maximum throughput. 
198
199 If not, but you can fit the entire database into the BDB cache, then you 
200 should do that and shrink the slapd entry cache as appropriate. 
201
202 Failing that, you should balance the BDB cache against the entry cache.
203
204 It is worth noting that it is not absolutely necessary to configure a BerkeleyDB 
205 cache equal in size to your entire database. All that you need is a cache 
206 that's large enough for your "working set." 
207
208 That means, large enough to hold all of the most frequently accessed data, 
209 plus a few less-frequently accessed items.
210
211 For more information, please see: {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/ref/am_conf/cachesize.html}}
212
213 H4: Calculating Cachesize
214
215 The back-bdb database lives in two main files, {{F:dn2id.bdb}} and {{F:id2entry.bdb}}. 
216 These are B-tree databases. We have never documented the back-bdb internal 
217 layout before, because it didn't seem like something anyone should have to worry 
218 about, nor was it necessarily cast in stone. But here's how it works today, 
219 in OpenLDAP 2.4.
220
221 A B-tree is a balanced tree; it stores data in its leaf nodes and bookkeeping 
222 data in its interior nodes (If you don't know what tree data structures look
223  like in general, Google for some references, because that's getting far too 
224 elementary for the purposes of this discussion).
225
226 For decent performance, you need enough cache memory to contain all the nodes 
227 along the path from the root of the tree down to the particular data item 
228 you're accessing. That's enough cache for a single search. For the general case, 
229 you want enough cache to contain all the internal nodes in the database. 
230
231 >       db_stat -d
232
233 will tell you how many internal pages are present in a database. You should 
234 check this number for both dn2id and id2entry.
235
236 Also note that {{id2entry}} always uses 16KB per "page", while {{dn2id}} uses whatever 
237 the underlying filesystem uses, typically 4 or 8KB. To avoid thrashing,
238 your cache must be at least as large as the number of internal pages in both 
239 the {{dn2id}} and {{id2entry}} databases, plus some extra space to accommodate
240 the actual leaf data pages.
241
242 For example, in my OpenLDAP 2.4 test database, I have an input LDIF file that's 
243 about 360MB. With the back-hdb backend this creates a {{dn2id.bdb}} that's 68MB, 
244 and an {{id2entry}} that's 800MB. db_stat tells me that {{dn2id}} uses 4KB pages, has 
245 433 internal pages, and 6378 leaf pages. The id2entry uses 16KB pages, has 52 
246 internal pages, and 45912 leaf pages. In order to efficiently retrieve any 
247 single entry in this database, the cache should be at least
248
249 >       (433+1) * 4KB + (52+1) * 16KB in size: 1736KB + 848KB =~ 2.5MB.
250
251 This doesn't take into account other library overhead, so this is even lower 
252 than the barest minimum. The default cache size, when nothing is configured, 
253 is only 256KB. 
254
255 This 2.5MB number also doesn't take indexing into account. Each indexed
256 attribute results in another database file.  Earlier versions of OpenLDAP
257 kept these index databases in Hash format, but from OpenLDAP 2.2 onward
258 the index databases are in B-tree format so the same procedure can
259 be used to calculate the necessary amount of cache for each index database.
260
261 For example, if your only index is for the objectClass attribute and db_stat
262 reveals that {{objectClass.bdb}} has 339 internal pages and uses 4096 byte
263 pages, the additional cache needed for just this attribute index is
264
265 >       (339+1) * 4KB =~ 1.3MB.
266
267 With only this index enabled, I'd figure at least a 4MB cache for this backend. 
268 (Of course you're using a single cache shared among all of the database files, 
269 so the cache pages will most likely get used for something other than what you 
270 accounted for, but this gives you a fighting chance.)
271
272 With this 4MB cache I can slapcat this entire database on my 1.3GHz PIII in 
273 1 minute, 40 seconds. With the cache doubled to 8MB, it still takes the same 1:40s. 
274 Once you've got enough cache to fit the B-tree internal pages, increasing it 
275 further won't have any effect until the cache really is large enough to hold 
276 100% of the data pages. I don't have enough free RAM to hold all the 800MB 
277 id2entry data, so 4MB is good enough.
278
279 With back-bdb and back-hdb you can use "db_stat -m" to check how well the 
280 database cache is performing. 
281
282 For more information on {{db_stat}}: {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/utility/db_stat.html}}
283
284 H3: {{slapd}}(8) Entry Cache (cachesize)
285
286 The {{slapd}}(8) entry cache operates on decoded entries. The rationale - entries 
287 in the entry cache can be used directly, giving the fastest response. If an entry 
288 isn't in the entry cache but can be extracted from the BDB page cache, that will 
289 avoid an I/O but it will still require parsing, so this will be slower. 
290
291 If the entry is in neither cache then BDB will have to flush some of its current 
292 cached pages and bring in the needed pages, resulting in a couple of expensive 
293 I/Os as well as parsing.
294
295 The most optimal value is of course, the entire number of entries in the database.  
296 However, most directory servers don't consistently serve out their entire database, so setting this to a lesser number that more closely matches the believed working set of data is 
297 sufficient. This is the second most important parameter for the DB.
298
299 As far as balancing the entry cache vs the BDB cache - parsed entries in memory 
300 are generally about twice as large as they are on disk. 
301
302 As we have already mentioned, not having a proper database cache size will 
303 cause performance issues. These issues are not an indication of corruption 
304 occurring in the database. It is merely the fact that the cache is thrashing 
305 itself that causes performance/response time to slowdown. 
306
307
308 H3: {{TERM:IDL}} Cache (idlcachesize)
309
310 Each IDL holds the search results from a given query, so the IDL cache will 
311 end up holding the most frequently requested search results.  For back-bdb, 
312 it is generally recommended to match the "cachesize" setting.  For back-hdb, 
313 it is generally recommended to be 3x"cachesize".
314
315 {NOTE: The idlcachesize setting directly affects search performance}
316
317
318 H3: {{slapd}}(8) Threads
319
320 {{slapd}}(8) can process requests via a configurable number of thread, which 
321 in turn affects the in/out rate of connections.
322
323 This value should generally be a function of the number of "real" cores on 
324 the system, for example on a server with 2 CPUs with one core each, set this 
325 to 8, or 4 threads per real core.  This is a "read" maximized value. The more 
326 threads that are configured per core, the slower {{slapd}}(8) responds for 
327 "read" operations.  On the flip side, it appears to handle write operations 
328 faster in a heavy write/low read scenario.
329
330 The upper bound for good read performance appears to be 16 threads (which
331 also happens to be the default setting).