]> git.sur5r.net Git - openldap/blob - doc/guide/admin/slapdconfig.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / slapdconfig.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: The slapd Configuration File
6
7 This chapter describes configuring {{slapd}}(8) via the {{slapd.conf}}(5)
8 configuration file.  {{slapd.conf}}(5) has been deprecated and should
9 only be used if your site requires one of the backends that hasn't yet
10 been updated to work with the newer {{slapd-config}}(5) system.  Configuring
11 {{slapd}}(8) via {{slapd-config}}(5) is described in the previous chapter.
12
13 The {{slapd.conf}}(5) file is normally installed in the
14 {{EX:/usr/local/etc/openldap}} directory.  An alternate configuration
15 file location can be specified via a command-line option to {{slapd}}(8).
16
17
18 H2: Configuration File Format
19
20 The {{slapd.conf}}(5) file consists of three types of configuration
21 information: global, backend specific, and database specific.  Global
22 information is specified first, followed by information associated
23 with a particular backend type, which is then followed by information
24 associated with a particular database instance.  Global directives can
25 be overridden in backend and/or database directives, and backend directives
26 can be overridden by database directives.
27
28 Blank lines and comment lines beginning with a '{{EX:#}}' character
29 are ignored.  If a line begins with whitespace, it is considered a
30 continuation of the previous line (even if the previous line is a
31 comment).
32
33 The general format of slapd.conf is as follows:
34
35 >       # global configuration directives
36 >       <global config directives>
37 >
38 >       # backend definition
39 >       backend <typeA>
40 >       <backend-specific directives>
41 >
42 >       # first database definition & config directives
43 >       database <typeA>
44 >       <database-specific directives>
45 >
46 >       # second database definition & config directives
47 >       database <typeB>
48 >       <database-specific directives>
49 >
50 >       # second database definition & config directives
51 >       database <typeA>
52 >       <database-specific directives>
53 >
54 >       # subsequent backend & database definitions & config directives
55 >       ...
56
57 A configuration directive may take arguments.  If so, they are
58 separated by whitespace.  If an argument contains whitespace,
59 the argument should be enclosed in double quotes {{EX:"like this"}}. If
60 an argument contains a double quote or a backslash character `{{EX:\}}',
61 the character should be preceded by a backslash character `{{EX:\}}'.
62
63 The distribution contains an example configuration file that will
64 be installed in the {{F: /usr/local/etc/openldap}} directory.
65 A number of files containing schema definitions (attribute types
66 and object classes) are also provided in the
67 {{F: /usr/local/etc/openldap/schema}} directory.
68
69
70 H2: Configuration File Directives
71
72 This section details commonly used configuration directives.  For
73 a complete list, see the {{slapd.conf}}(5) manual page.  This section
74 separates the configuration file directives into global,
75 backend-specific and data-specific categories, describing each
76 directive and its default value (if any), and giving an example of
77 its use.
78
79
80
81 H3: Global Directives
82
83 Directives described in this section apply to all backends
84 and databases unless specifically overridden in a backend or
85 database definition.  Arguments that should be replaced
86 by actual text are shown in brackets {{EX:<>}}.
87
88
89 H4: access to <what> [ by <who> [<accesslevel>] [<control>] ]+
90
91 This directive grants access (specified by <accesslevel>) to a set
92 of entries and/or attributes (specified by <what>) by one or more
93 requestors (specified by <who>).  See the {{SECT:Access Control}} section of 
94 this guide for basic usage.
95
96 !if 0
97 More details discussion of this directive can be found in the
98 {{SECT:Advanced Access Control}} chapter.
99 !endif
100
101 Note: If no {{EX:access}} directives are specified, the default
102 access control policy, {{EX:access to * by * read}}, allows all
103 both authenticated and anonymous users read access.
104
105
106 H4: attributetype <{{REF:RFC4512}} Attribute Type Description>
107
108 This directive defines an attribute type.
109 Please see the {{SECT:Schema Specification}} chapter
110 for information regarding how to use this directive.
111
112 H4: idletimeout <integer>
113
114 Specify the number of seconds to wait before forcibly closing
115 an idle client connection.  An idletimeout of 0, the default,
116 disables this feature.
117
118
119 H4: include <filename>
120
121 This directive specifies that slapd should read additional
122 configuration information from the given file before continuing
123 with the next line of the current file. The included file should
124 follow the normal slapd config file format.  The file is commonly
125 used to include files containing schema specifications.
126
127 Note: You should be careful when using this directive - there is
128 no small limit on the number of nested include directives, and no
129 loop detection is done.
130
131 H4: loglevel <level>
132
133 This directive specifies the level at which debugging statements
134 and operation statistics should be syslogged (currently logged to
135 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
136 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
137 to work (except for the two statistics levels, which are always
138 enabled). Log levels may be specified as integers or by keyword.
139 Multiple log levels may be used and the levels are additive. To display what
140 numbers correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
141 or consult the table below. The possible values for <integer> are:
142
143 !block table; colaligns="RL"; align=Center; \
144         title="Table 6.1: Debugging Levels"
145 Level   Keyword         Description
146 -1      any             enable all debugging
147 0                       no debugging
148 1       (0x1 trace)     trace function calls
149 2       (0x2 packets)   debug packet handling
150 4       (0x4 args)      heavy trace debugging
151 8       (0x8 conns)     connection management
152 16      (0x10 BER)      print out packets sent and received
153 32      (0x20 filter)   search filter processing
154 64      (0x40 config)   configuration processing
155 128     (0x80 ACL)      access control list processing
156 256     (0x100 stats)   stats log connections/operations/results
157 512     (0x200 stats2)  stats log entries sent
158 1024    (0x400 shell)   print communication with shell backends
159 2048    (0x800 parse)   print entry parsing debugging
160 16384   (0x4000 sync)   syncrepl consumer processing
161 32768   (0x8000 none)   only messages that get logged whatever log level is set
162 !endblock
163
164 The desired log level can be input as a single integer that
165 combines the (ORed) desired levels, both in decimal or in hexadecimal 
166 notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that
167
168 >               loglevel 129
169 >               loglevel 0x81
170 >               loglevel 128 1
171 >               loglevel 0x80 0x1
172 >               loglevel acl trace
173
174 are equivalent.
175
176 \Examples:
177
178 E: loglevel -1
179
180 This will cause lots and lots of debugging information to be
181 logged.
182
183 E: loglevel conns filter
184
185 Just log the connection and search filter processing.
186
187 E: loglevel none
188
189 Log those messages that are logged regardless of the configured loglevel. This
190 differs from setting the log level to 0, when no logging occurs. At least the
191 {{EX:None}} level is required to have high priority messages logged.
192
193 \Default:
194
195 E: loglevel stats
196
197 Basic stats logging is configured by default. However, if no loglevel is
198 defined, no logging occurs (equivalent to a 0 level).
199
200 H4: objectclass <{{REF:RFC4512}} Object Class Description>
201
202 This directive defines an object class.
203 Please see the {{SECT:Schema Specification}} chapter for
204 information regarding how to use this directive.
205
206
207 H4: referral <URI>
208
209 This directive specifies the referral to pass back when slapd
210 cannot find a local database to handle a request.
211
212 \Example:
213
214 >       referral ldap://root.openldap.org
215
216 This will refer non-local queries to the global root LDAP server
217 at the OpenLDAP Project. Smart LDAP clients can re-ask their
218 query at that server, but note that most of these clients are
219 only going to know how to handle simple LDAP URLs that
220 contain a host part and optionally a distinguished name part.
221
222
223 H4: sizelimit <integer>
224
225 This directive specifies the maximum number of entries to return
226 from a search operation.
227
228 \Default:
229
230 >       sizelimit 500
231
232 See the {{SECT:Limits}} section of this guide and slapd.conf(5)
233 for more details.
234
235 H4: timelimit <integer>
236
237 This directive specifies the maximum number of seconds (in real
238 time) slapd will spend answering a search request. If a
239 request is not finished in this time, a result indicating an
240 exceeded timelimit will be returned.
241
242 \Default:
243
244 >       timelimit 3600
245
246 See the {{SECT:Limits}} section of this guide and slapd.conf(5)
247 for more details.
248
249
250 H3: General Backend Directives
251
252 Directives in this section apply only to the backend in which
253 they are defined. They are supported by every type of backend.
254 Backend directives apply to all databases instances of the
255 same type and, depending on the directive, may be overridden
256 by database directives.
257
258 H4: backend <type>
259
260 This directive marks the beginning of a backend declaration.
261 {{EX:<type>}} should be one of the
262 supported backend types listed in Table 6.2.
263
264 !block table; align=Center; coltags="EX,N"; \
265         title="Table 6.2: Database Backends"
266 Types   Description
267 bdb     Berkeley DB transactional backend
268 dnssrv  DNS SRV backend
269 hdb     Hierarchical variant of bdb backend
270 ldap    Lightweight Directory Access Protocol (Proxy) backend
271 meta    Meta Directory backend
272 monitor Monitor backend
273 passwd  Provides read-only access to {{passwd}}(5)
274 perl    Perl Programmable backend
275 shell   Shell (extern program) backend
276 sql     SQL Programmable backend
277 !endblock
278
279 \Example:
280
281 >       backend bdb
282
283 This marks the beginning of a new {{TERM:BDB}} backend
284 definition.
285
286
287 H3: General Database Directives
288
289 Directives in this section apply only to the database in which
290 they are defined. They are supported by every type of database.
291
292 H4: database <type>
293
294 This directive marks the beginning of a database instance
295 declaration.
296 {{EX:<type>}} should be one of the
297 supported backend types listed in Table 6.2.
298
299 \Example:
300
301 >       database bdb
302
303 This marks the beginning of a new {{TERM:BDB}} database instance
304 declaration.
305
306
307 H4: limits <who> <limit> [<limit> [...]]
308
309 Specify time and size limits based on who initiated an operation.
310
311 See the {{SECT:Limits}} section of this guide and slapd.conf(5)
312 for more details.
313
314
315 H4: readonly { on | off }
316
317 This directive puts the database into "read-only" mode. Any
318 attempts to modify the database will return an "unwilling to
319 perform" error.
320
321 \Default:
322
323 >       readonly off
324
325
326 H4: rootdn <DN>
327
328 This directive specifies the DN that is not subject to
329 access control or administrative limit restrictions for
330 operations on this database.  The DN need not refer to
331 an entry in this database or even in the directory. The
332 DN may refer to a SASL identity.
333
334 Entry-based Example:
335
336 >       rootdn "cn=Manager,dc=example,dc=com"
337
338 SASL-based Example:
339
340 >       rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
341
342 See the {{SECT:SASL Authentication}} section for information on
343 SASL authentication identities.
344
345
346 H4: rootpw <password>
347
348 This directive can be used to specifies a password for the DN for
349 the rootdn (when the rootdn is set to a DN within the database).
350
351 \Example:
352
353 >       rootpw secret
354
355 It is also permissible to provide hash of the password in {{REF:RFC2307}}
356 form.  {{slappasswd}}(8) may be used to generate the password hash.
357
358 \Example:
359
360 >       rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
361
362 The hash was generated using the command {{EX:slappasswd -s secret}}.
363
364
365 H4: suffix <dn suffix>
366
367 This directive specifies the DN suffix of queries that will be
368 passed to this backend database. Multiple suffix lines can be
369 given, and at least one is required for each database
370 definition.
371
372 \Example:
373
374 >       suffix "dc=example,dc=com"
375
376 Queries with a DN ending in "dc=example,dc=com"
377 will be passed to this backend.
378
379 Note: When the backend to pass a query to is selected, slapd
380 looks at the suffix line(s) in each database definition in the
381 order they appear in the file. Thus, if one database suffix is a
382 prefix of another, it must appear after it in the config file.
383
384
385 H4: syncrepl
386
387 >       syncrepl rid=<replica ID>
388 >               provider=ldap[s]://<hostname>[:port]
389 >               [type=refreshOnly|refreshAndPersist]
390 >               [interval=dd:hh:mm:ss]
391 >               [retry=[<retry interval> <# of retries>]+]
392 >               searchbase=<base DN>
393 >               [filter=<filter str>]
394 >               [scope=sub|one|base]
395 >               [attrs=<attr list>]
396 >               [attrsonly]
397 >               [sizelimit=<limit>]
398 >               [timelimit=<limit>]
399 >               [schemachecking=on|off]
400 >               [bindmethod=simple|sasl]
401 >               [binddn=<DN>]
402 >               [saslmech=<mech>]
403 >               [authcid=<identity>]
404 >               [authzid=<identity>]
405 >               [credentials=<passwd>]
406 >               [realm=<realm>]
407 >               [secprops=<properties>]
408 >               [starttls=yes|critical]
409 >               [tls_cert=<file>]
410 >               [tls_key=<file>]
411 >               [tls_cacert=<file>]
412 >               [tls_cacertdir=<path>]
413 >               [tls_reqcert=never|allow|try|demand]
414 >               [tls_ciphersuite=<ciphers>]
415 >               [tls_crlcheck=none|peer|all]
416 >               [logbase=<base DN>]
417 >               [logfilter=<filter str>]
418 >               [syncdata=default|accesslog|changelog]
419
420
421 This directive specifies the current database as a replica of the
422 master content by establishing the current {{slapd}}(8) as a
423 replication consumer site running a syncrepl replication engine.
424 The master database is located at the replication provider site
425 specified by the {{EX:provider}} parameter. The replica database is
426 kept up-to-date with the master content using the LDAP Content
427 Synchronization protocol. See {{REF:RFC4533}}
428 for more information on the protocol.
429
430 The {{EX:rid}} parameter is used for identification of the current
431 {{EX:syncrepl}} directive within the replication consumer server,
432 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
433 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
434 is non-negative and is no more than three decimal digits in length.
435
436 The {{EX:provider}} parameter specifies the replication provider site
437 containing the master content as an LDAP URI. The {{EX:provider}}
438 parameter specifies a scheme, a host and optionally a port where the
439 provider slapd instance can be found. Either a domain name or IP
440 address may be used for <hostname>. Examples are
441 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
442 If <port> is not given, the standard LDAP port number (389 or 636) is used.
443 Note that the syncrepl uses a consumer-initiated protocol, and hence its
444 specification is located at the consumer site, whereas the {{EX:replica}}
445 specification is located at the provider site. {{EX:syncrepl}} and
446 {{EX:replica}} directives define two independent replication
447 mechanisms. They do not represent the replication peers of each other.
448
449 The content of the syncrepl replica is defined using a search
450 specification as its result set. The consumer slapd will
451 send search requests to the provider slapd according to the search
452 specification. The search specification includes {{EX:searchbase}},
453 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
454 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
455 search specification. The {{EX:searchbase}} parameter has no
456 default value and must always be specified. The {{EX:scope}} defaults
457 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
458 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
459 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
460 and {{EX:timelimit}} default to "unlimited", and only positive integers
461 or "unlimited" may be specified.
462
463 The {{TERM[expand]LDAP Sync}} protocol has two operation
464 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
465 The operation type is specified by the {{EX:type}} parameter.
466 In the {{EX:refreshOnly}} operation, the next synchronization search operation
467 is periodically rescheduled at an interval time after each
468 synchronization operation finishes. The interval is specified
469 by the {{EX:interval}} parameter. It is set to one day by default.
470 In the {{EX:refreshAndPersist}} operation, a synchronization search
471 remains persistent in the provider {{slapd}} instance. Further updates to the
472 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
473 as the search responses to the persistent synchronization search.
474
475 If an error occurs during replication, the consumer will attempt to reconnect
476 according to the retry parameter which is a list of the <retry interval>
477 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
478 retry every 60 seconds for the first 10 times and then retry every 300 seconds
479 for the next three times before stop retrying. + in <#  of retries> means
480 indefinite number of retries until success.
481
482 The schema checking can be enforced at the LDAP Sync consumer site
483 by turning on the {{EX:schemachecking}} parameter.
484 If it is turned on, every replicated entry will be checked for its
485 schema as the entry is stored into the replica content.
486 Every entry in the replica should contain those attributes
487 required by the schema definition.
488 If it is turned off, entries will be stored without checking
489 schema conformance. The default is off.
490
491 The {{EX:binddn}} parameter gives the DN to bind as for the
492 syncrepl searches to the provider slapd. It should be a DN
493 which has read access to the replication content in the
494 master database. 
495
496 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
497 depending on whether simple password-based authentication or
498 {{TERM:SASL}} authentication is to be used when connecting
499 to the provider {{slapd}} instance.
500
501 Simple authentication should not be used unless adequate data
502 integrity and confidentiality protections are in place (e.g. TLS
503 or IPsec). Simple authentication requires specification of {{EX:binddn}}
504 and {{EX:credentials}} parameters.
505
506 SASL authentication is generally recommended.  SASL authentication
507 requires specification of a mechanism using the {{EX:saslmech}} parameter.
508 Depending on the mechanism, an authentication identity and/or
509 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
510 respectively.  The {{EX:authzid}} parameter may be used to specify
511 an authorization identity.
512
513 The {{EX:realm}} parameter specifies a realm which a certain
514 mechanisms authenticate the identity within. The {{EX:secprops}}
515 parameter specifies Cyrus SASL security properties.
516
517 The {{EX:starttls}} parameter specifies use of the StartTLS extended
518 operation to establish a TLS session before authenticating to the provider.
519 If the {{EX:critical}} argument is supplied, the session will be aborted
520 if the StartTLS request fails.  Otherwise the syncrepl session continues
521 without TLS.  Note that the main slapd TLS settings are not used by the
522 syncrepl engine; by default the TLS parameters from a {{ldap.conf}}(5)
523 configuration file will be used.  TLS settings may be specified here,
524 in which case any {{ldap.conf}}(5) settings will be completely ignored.
525
526 Rather than replicating whole entries, the consumer can query logs
527 of data modifications.  This mode of operation is referred to as
528 {{delta syncrepl}}.  In addition to the above parameters, the
529 {{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
530 for the log that will be used. The {{EX:syncdata}} parameter must
531 be set to either {{EX:"accesslog"}} if the log conforms to the
532 {{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
533 conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
534 parameter is omitted or set to {{EX:"default"}} then the log
535 parameters are ignored.
536
537 The {{syncrepl}} replication mechanism is supported by the {{bdb}} and
538 {{hdb}} backends.
539
540 See the {{SECT:LDAP Sync Replication}} chapter of this guide for
541 more information on how to use this directive.
542
543
544 H4: updateref <URL>
545
546 This directive is only applicable in a {{slave}} (or {{shadow}})
547 {{slapd}}(8) instance. It
548 specifies the URL to return to clients which submit update
549 requests upon the replica.
550 If specified multiple times, each {{TERM:URL}} is provided.
551
552 \Example:
553
554 >       updateref       ldap://master.example.net
555
556
557 H3: BDB and HDB Database Directives
558
559 Directives in this category only apply to both the {{TERM:BDB}}
560 and the {{TERM:HDB}} database.
561 That is, they must follow a "database bdb" or "database hdb" line
562 and come before any
563 subsequent "backend" or "database" line.  For a complete reference
564 of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
565
566
567 H4: directory <directory>
568
569 This directive specifies the directory where the BDB files
570 containing the database and associated indices live.
571
572 \Default:
573
574 >       directory /usr/local/var/openldap-data
575
576
577 H2: Configuration File Example
578
579 The following is an example configuration file, interspersed
580 with explanatory text. It defines two databases to handle
581 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
582 database instances. The line numbers shown are provided for
583 reference only and are not included in the actual file. First, the
584 global configuration section:
585
586 E:  1.    # example config file - global configuration section
587 E:  2.    include /usr/local/etc/schema/core.schema
588 E:  3.    referral ldap://root.openldap.org
589 E:  4.    access to * by * read
590  
591 Line 1 is a comment. Line 2 includes another config file
592 which contains {{core}} schema definitions.
593 The {{EX:referral}} directive on line 3
594 means that queries not local to one of the databases defined
595 below will be referred to the LDAP server running on the
596 standard port (389) at the host {{EX:root.openldap.org}}.
597
598 Line 4 is a global access control.  It applies to all
599 entries (after any applicable database-specific access
600 controls).
601
602 The next section of the configuration file defines a BDB
603 backend that will handle queries for things in the
604 "dc=example,dc=com" portion of the tree. The
605 database is to be replicated to two slave slapds, one on
606 truelies, the other on judgmentday. Indices are to be
607 maintained for several attributes, and the {{EX:userPassword}}
608 attribute is to be protected from unauthorized access.
609
610 E:  5.    # BDB definition for the example.com
611 E:  6.    database bdb
612 E:  7.    suffix "dc=example,dc=com"
613 E:  8.    directory /usr/local/var/openldap-data
614 E:  9.    rootdn "cn=Manager,dc=example,dc=com"
615 E: 10.    rootpw secret
616 E: 11.    # indexed attribute definitions
617 E: 12.    index uid pres,eq
618 E: 13.    index cn,sn,uid pres,eq,approx,sub
619 E: 14.    index objectClass eq
620 E: 15.    # database access control definitions
621 E: 16.    access to attrs=userPassword
622 E: 17.        by self write
623 E: 18.        by anonymous auth
624 E: 19.        by dn.base="cn=Admin,dc=example,dc=com" write
625 E: 20.        by * none
626 E: 21.    access to *
627 E: 22.        by self write
628 E: 23.        by dn.base="cn=Admin,dc=example,dc=com" write
629 E: 24.        by * read
630
631 Line 5 is a comment. The start of the database definition is marked
632 by the database keyword on line 6. Line 7 specifies the DN suffix
633 for queries to pass to this database. Line 8 specifies the directory
634 in which the database files will live.
635
636 Lines 9 and 10 identify the database {{super-user}} entry and associated
637 password. This entry is not subject to access control or size or
638 time limit restrictions.
639
640 Lines 12 through 14 indicate the indices to maintain for various
641 attributes.
642
643 Lines 16 through 24 specify access control for entries in this
644 database. For all applicable entries, the {{EX:userPassword}} attribute is writable
645 by the entry itself and by the "admin" entry.  It may be used for
646 authentication/authorization purposes, but is otherwise not readable.
647 All other attributes are writable by the entry and the "admin"
648 entry, but may be read by all users (authenticated or not).
649
650 The next section of the example configuration file defines another
651 BDB database. This one handles queries involving the
652 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
653 as the first database.  Note that without line 39, the read access
654 would be allowed due to the global access rule at line 4.
655
656 E: 33.    # BDB definition for example.net
657 E: 34.    database bdb
658 E: 35.    suffix "dc=example,dc=net"
659 E: 36.    directory /usr/local/var/openldap-data-net
660 E: 37.    rootdn "cn=Manager,dc=example,dc=com"
661 E: 38.    index objectClass eq
662 E: 39.    access to * by users read