4 LDAP Data Interchange Format (LDIF) Gordon Good
5 INTERNET-DRAFT Netscape Communications
8 The LDAP Data Interchange Format (LDIF) - Technical Specification
9 Filename: draft-good-ldap-ldif-03.txt
13 This document is an Internet-Draft and is in full conformance
14 with all provisions of Section 10 of RFC2026.
16 Internet-Drafts are working documents of the Internet Engineering
17 Task Force (IETF), its areas, and its working groups. Note that
18 other groups may also distribute working documents as
21 Internet-Drafts are draft documents valid for a maximum of six
22 months and may be updated, replaced, or obsoleted by other
23 documents at any time. It is inappropriate to use Internet-
24 Drafts as reference material or to cite them other than as
27 To view the list Internet-Draft Shadow Directories, see
28 http://www.ietf.org/shadow.html.
30 This Internet Draft expires August 22nd, 1999.
35 This document describes a file format suitable for describing
36 directory information or modifications made to directory information.
37 The file format, known as LDIF, for LDAP Data Interchange Format, is
38 typically used to import and export directory information between
39 LDAP-based directory servers, or to describe a set of changes which
40 are to be applied to a directory.
43 Background and Intended Usage
45 There are a number of situations where a common interchange format is
46 desirable. For example, one might wish to export a copy of the
47 contents of a directory server to a file, move that file to a
48 different machine, and import the contents into a second directory
51 Additionally, by using a well-defined interchange format, development
55 Good February 22, 1999 [Page 1]
57 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
60 of data import tools from legacy systems is facilitated. A fairly
61 simple set of tools written in awk or perl can, for example, convert
62 a database of personnel information into an LDIF file. Thie file can
63 then be imported into a directory server, regardless of the internal
64 database representation the target directory server uses.
66 The LDIF format was originally developed and used in the University
67 of Michigan LDAP implementation. The first use of LDIF was in
68 describing directory entries. Later, the format was expanded to
69 allow representation of changes to directory entries.
71 Relationship to the application/directory MIME content-type:
73 The application/directory MIME content-type [1] is a general
74 framework and format for conveying directory information, and is
75 independent of any particular directory service. The LDIF format is
76 a simpler format which is perhaps easier to create, and also may also
77 be used, as noted, to describe a set of changes to be applied to a
80 The key words "MUST", "MAY", and "SHOULD" used in this document are
81 to be interpreted as described in [7].
84 Definition of the LDAP Data Interchange Format
87 The LDIF format is used to convey directory information, or a
88 description of a set of changes made to directory entries. An LDIF
89 file consists of a series of records separated by line separators. A
90 record consists of a sequence of lines describing a directory entry,
91 or a sequence of lines describing a set of changes to a directory
92 entry. An LDIF file specifies a set of directory entries, or a set
93 of changes to be applied to directory entries, but not both.
95 There is a one-to-one correlation between LDAP operations which
96 modify the directory (add, delete, modify, and modrdn), and the types
97 of changerecords described below ("add", "delete", "modify", and
98 "modrdn" or "moddn"). This correspondence is intentional, and
99 permits a straightforward translation from LDIF changerecords to
102 Formal Syntax Definition of LDIF
104 The following definition uses the augmented Backus-Naur Form
105 specified in RFC 822 [2].
107 ldif-file = ldif-content / ldif-changes
111 Good February 22, 1999 [Page 2]
113 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
116 ldif-content = version-spec 1*SEP
117 ldif-attrval-record *(1*SEP ldif-attrval-record)
118 ldif-changes = version-spec 1*SEP
119 ldif-change-record *(1*SEP ldif-change-record)
120 ldif-attrval-record = dn-spec SEP 1*(attrval-spec SEP)
121 ldif-change-record = dn-spec SEP 1*(changerecord SEP)
123 version-spec = "version:" *SPACE version-number
124 version-number = 1*DIGIT ; version-number MUST be "1" for the
125 ; LDIF format described in this document.
127 dn-spec = ("dn:" *SPACE dn) / ("dn::" *SPACE base64-dn)
128 dn = <a distinguished name, as defined in RFC 2253 [3]>
129 base64-dn = <a dn which has been base-64 encoded, as
130 defined in RFC 1521 [5]>
131 rdn = <a relative distinguished name, as defined in RFC
133 base64-rdn = <an rdn which has been base-64 encoded, as
134 defined in RFC 1521 [5]>
136 attrval-spec = attribute-description ((":") / (":" *SPACE value) /
137 ("::" *SPACE base64-value) /
139 url = <a Uniform Resource Locator, as defined in [6]>
140 ; (See Note 6, below)
141 attribute-description = <an attribute description, as defined in [4].
142 An attribute description MAY NOT contain a
144 value = 1*safe-initval *safe
145 ; (See Note 9, below)
146 safe = <any value except CR or LF>
147 safe-initval = <any value except CR, LF, colon (":", ASCII 58
148 decimal), SPACE, and less-than ("<" , ASCII 60
150 base64-value = <base-64-encoded value, as defined in RFC 1521 [5]>
152 changerecord = change-add / change-delete / change-modify /
154 change-add = "changetype:" *SPACE "add" 1*(SEP attrval-spec)
155 change-delete = "changetype:" *SPACE "delete"
156 change-moddn = "changetype:" *SPACE ("modrdn" / "moddn") SEP
157 ("newrdn:" *SPACE rdn /
158 "newrdn::" *SPACE base-64-rdn) SEP
159 "deleteoldrdn:" *SPACE ("0" / "1")
160 0,1*(SEP (("newsuperior:" *SPACE dn) /
161 ("newsuperior::" *SPACE base-64-dn)))
162 change-modify = "changetype:" *SPACE "modify" 1*(SEP mod-spec)
163 mod-spec = mod-add-spec / mod-delete-spec / mod-replace-spec
167 Good February 22, 1999 [Page 3]
169 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
172 mod-add-spec = "add:" *SPACE attribute-description
173 1*(SEP attrval-spec) SEP "-"
174 mod-delete-spec = "delete:" *SPACE attribute-description
175 *(SEP attrval-spec) SEP "-"
176 mod-replace-spec = "replace:" *SPACE attribute-description
177 *(SEP attrval-spec) SEP "-"
178 SPACE = <ASCII SP, space>
180 CR = <ASCII CR, carriage return>
181 LF = <ASCII LF, line feed>
182 DIGIT = <any ASCII decimal digit (60 - 71 decimal) >
187 1) For the LDIF format described in this document, the version number
188 MUST be "1". If the version number is absent, implementations MAY
189 choose to interpret the contents as an older LDIF file format,
190 supported by the University of Michigan ldap-3.3 implementation [8].
192 2) Any line, including comment lines, in an LDIF file MAY be wrapped
193 by inserting a line separator (SEP) and a SPACE. Any line which
194 begins with a single space MUST be treated as a continuation of the
195 previous line. When joining folded lines, exactly one space character
196 at the beginning of each continued line must be discarded.
198 3) Any line which begins with a pound-sign ("#", ASCII 35) is a
199 comment line, and MUST be ignored when parsing an LDIF file.
201 4) Any dn or value which contains characters other than those defined
202 as "safe", or begins with a character other than those defined as
203 "safe-initval", above, MUST be base-64 encoded. Other values MAY be
206 5) To represent a zero-length attribute value, use an attrval-spec of
207 "attribute-description:". For example, "seeAlso:" represents a
208 zero-length "seeAlso" attribute value.
210 6) When a URL is specified in an attrval-spec, the following
212 a) Implementations SHOULD support the file:// URL format. The
213 contents of the referenced file are to be included verbatim
214 in the interpreted output of the LDIF file.
215 b) Implementations MAY support other URL formats. The semantics
216 associated with each supported URL will be documented in
217 an associated Applicability Statement.
219 7) While it is permissible for character values larger than 126 to be
223 Good February 22, 1999 [Page 4]
225 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
228 contained in an attribute value, implementations SHOULD base-64
229 encode any value which contains such characters when generating LDIF.
230 However, implementations MAY leave the values unencoded. This
231 relaxation is designed to allow editing of LDIF files containing
234 8) Attribute values contained in LDIF files represent directory data,
235 and therefore MUST be valid UTF-8 strings. Implementations which read
236 LDIF MAY interpret files in which the values are stored in some other
237 character set encoding, but implementations MUST NOT generate LDIF
238 content which does not contain valid UTF-8 data.
240 9) Values that end with SPACE SHOULD be base-64 encoded.
242 Examples of LDAP Data Interchange Format
245 Example 1: An simple LDAP file with two entries
248 dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
251 objectclass: organizationalPerson
257 telephonenumber: +1 408 555 1212
258 description: A big sailing fan.
260 dn: cn=Bjorn Jensen, ou=Accounting, dc=airius, dc=com
263 objectclass: organizationalPerson
266 telephonenumber: +1 408 555 1212
268 Example 2: A file containing an entry with a folded attribute value
271 dn:cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
274 objectclass:organizationalPerson
279 Good February 22, 1999 [Page 5]
281 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
288 telephonenumber:+1 408 555 1212
289 description:Babs is a big sailing fan, and travels extensively in search of
290 perfect sailing conditions.
291 title:Product Manager, Rod and Reel Division
293 Example 3: A file containing a base-64-encoded value
296 dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com
299 objectclass: organizationalPerson
304 telephonenumber: +1 408 555 1212
305 description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ
306 hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh
307 hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu
309 Example 4: A file containing an entries with UTF-8-encoded attribute
310 values, including language tags. Comments indicate the contents
311 of UTF-8-encoded attributes and distinguished names.
314 dn:: b3U95Za25qWt6YOoLG89QWlyaXVz
315 # dn:: ou=<JapaneseOU>,o=Airius
317 objectclass: organizationalUnit
320 ou;lang-ja:: 5Za25qWt6YOo
321 # ou;lang-ja:: <JapaneseOU>
322 ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2
323 # ou;lang-ja:: <JapaneseOU_in_phonetic_representation>
325 description: Japanese office
327 dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz
328 # dn:: uid=<uid>,ou=<JapaneseOU>,o=Airius
329 userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM=
335 Good February 22, 1999 [Page 6]
337 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
340 objectclass: organizationalPerson
341 objectclass: inetOrgPerson
343 mail: rogasawara@airius.co.jp
344 givenname;lang-ja:: 44Ot44OJ44OL44O8
345 # givenname;lang-ja:: <JapaneseGivenname>
346 sn;lang-ja:: 5bCP56yg5Y6f
347 # sn;lang-ja:: <JapaneseSn>
348 cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
349 # cn;lang-ja:: <JapaneseCn>
350 title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw==
351 # title;lang-ja:: <JapaneseTitle>
352 preferredlanguage: ja
353 givenname:: 44Ot44OJ44OL44O8
354 # givenname:: <JapaneseGivenname>
357 cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
359 title:: 5Za25qWt6YOoIOmDqOmVtw==
360 # title:: <JapaneseTitle>
361 givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8
362 # givenname;lang-ja;phonetic::
363 <JapaneseGivenname_in_phonetic_representation_kana>
364 sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ
365 # sn;lang-ja;phonetic:: <JapaneseSn_in_phonetic_representation_kana>
366 cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA==
367 # cn;lang-ja;phonetic:: <JapaneseCn_in_phonetic_representation_kana>
368 title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg==
369 # title;lang-ja;phonetic:: <JapaneseTitle_in_phonetic_representation_kana>
370 givenname;lang-en: Rodney
371 sn;lang-en: Ogasawara
372 cn;lang-en: Rodney Ogasawara
373 title;lang-en: Sales, Director
375 Example 5: A file containing a reference to an external file
378 dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com
381 objectclass: organizationalPerson
386 telephonenumber: +1 408 555 1212
387 jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg
391 Good February 22, 1999 [Page 7]
393 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
396 Example 6: A file containing a series of change records and comments
400 dn: cn=Fiona Jensen, ou=Marketing, dc=airius, dc=com
404 objectclass: organizationalPerson
408 telephonenumber: +1 408 555 1212
409 jpegphoto:< file:///usr/local/directory/photos/fiona.jpg
411 # Delete an existing entry
412 dn: cn=Robert Jensen, ou=Marketing, dc=airius, dc=com
415 # Modify an entry's relative distinguished name
416 dn: cn=Paul Jensen, ou=Product Development, dc=airius, dc=com
418 newrdn: cn=Paula Jensen
421 # Rename an entry and move all of its children to a new location in
422 # the directory tree (only implemented by LDAPv3 servers).
423 dn: ou=PD Accountants, ou=Product Development, dc=airius, dc=com
425 newrdn: ou=Product Development Accountants
427 newsuperior: ou=Accounting, dc=airius, dc=com
429 # Modify an entry: add an additional value to the postaladdress attribute,
430 # completely delete the description attribute, replace the telephonenumber
431 # attribute with two values, and delete a specific value from the
432 # facsimiletelephonenumber attribute
433 dn: cn=Paula Jensen, ou=Product Development, dc=airius, dc=com
436 postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086
440 replace: telephonenumber
441 telephonenumber: +1 408 555 1234
442 telephonenumber: +1 408 555 5678
447 Good February 22, 1999 [Page 8]
449 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
452 delete: facsimiletelephonenumber
453 facsimiletelephonenumber: +1 408 555 9876
457 Security Considerations
459 Given typical directory applications, an LDIF file is likely to
460 contain sensitive personal data. Appropriate measures should be
461 taken to protect the privacy of those persons whose data is contained
464 Since ":<" directives can cause external content to be included when
465 processing an LDIF file, one should be cautious of accepting LDIF
466 files from external sources. A "trojan" LDIF file could name a file
467 with sensitive contents and cause it to be included in a directory
468 entry, which a hostile entity could read via LDAP.
470 LDIF does not provide any method for carrying authentication
471 information with an LDIF file. Users of LDIF files must take care to
472 verify the integrity of an LDIF file received from an external
475 Appendix A: Differences from previous versions of this document
477 This section summarizes the differences between previous revisions of
478 this draft, as an aid to document reviewers. This section will be
479 deleted prior to publication as an RFC.
481 Differences between draft-ietf-asid-ldif-00.txt and draft-ietf-asid-
484 1) The BNF has been modified to explicitly disallow ldif content and
485 change records in the same file. In other words, a given LDIF file
486 is either a series of directory entries, or a series of
487 modifications. An LDIF file MUST NOT contain both types of records.
489 2) External references are now URLs, instead of simple filenames.
491 3) The BNF has been modified to allow base-64-encoded distinguished
494 4) Multiple separators are now permitted between records.
496 Differences between draft-ietf-asid-ldif-01.txt and draft-ietf-asid-
499 1) The BNF has been modified such that a simple attribute name
503 Good February 22, 1999 [Page 9]
505 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
508 ("attrname") has been replaced with an "attribute-description" as
509 defined in the LDAPv3 protocol document [4]. This permits language
510 codes and other attribute options to be carried in an LDIF file.
512 2) A new option, "charset", may be used in attribute descriptions.
513 This facilitates multi-lingual character set conversion.
515 3) The definition of the "safe" and "safe-initval" productions has
516 been relaxed to allow non-ASCII characters with values greater than
517 126. This permits more natural expression of character sets such as
518 Latin-1 in LDIF files.
520 Differences between draft-ietf-asid-ldif-02.txt and draft-good-ldap-
523 1) The "charset-option" and "charset-name" productions were removed
524 from the BNF, due to objections within the working group. UTF-8 is
525 the only character set which may be used in LDIF.
527 2) Examples were reworked to reflect the above change, and to include
528 an example of a non-western language represented in UTF-8.
530 Differences between draft-ietf-good-ldif-00.txt and draft-good-ldap-
533 1) Added version identifiers to the examples - they were missing.
535 2) Clarified that LDIF file must use UTF-8.
537 Differences between draft-ietf-good-ldif-01.txt and draft-good-ldap-
540 1) Added a recommendation that values ending in SPACE should be
543 2) Clarified the procedure for joining folded lines.
545 3) Updated header to reflect new IETF I-D guidelines.
547 Differences between draft-ietf-good-ldif-02.txt and draft-good-ldap-
550 1) Fixed reference from RFC 1779 to RFC 2253.
552 2) Version string is now required.
554 3) Comment lines may be folded (this is now explicitly mentioned in
559 Good February 22, 1999 [Page 10]
561 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
564 4) Moved this section (differences between draft versions) to an
567 5) Updated examples to use "dc=airius, dc=com" instead of "o=Ace
570 6) Cleaned up references section.
575 The LDAP Interchange Format was developed as part of the University
576 of Michigan LDAP reference implementation, and was developed by Tim
577 Howes, Mark Smith, and Gordon Good. It is based in part upon work
578 supported by the National Science Foundation under Grant No. NCR-
585 [1] Howes, T., Smith, M., "A MIME Content-Type for Directory Infor-
586 mation", RFC 2425, September 1998,
587 <URL:http://www.ietf.org/rfc/rfc2245.txt>
589 [2] Crocker, D.H., "Standard for the Format of ARPA Internet Text
590 Messages", RFC 822, August 1982,
591 <URL:http://ds.internic.net/rfc/rfc822.txt>
593 [3] Wahl, M., Kille, S., Howes, T., "A String Representation of Dis-
594 tinguished Names", RFC 2253,
595 <URL:http://www.ietf.org/rfc/rfc2253.txt>
597 [4] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
598 Protocol (v3)", RFC 2251, July, 1997,
599 <URL:ftp://www.ietf.org/rfc/rfc2251.txt>
601 [5] Borenstein, N., Freed, N., "MIME (Multipurpose Internet Mail
602 Extensions) Part One: Mechanisms for Specifying and Describing
603 the Format of Internet Message Bodies", section 5.2, "Base64
604 Content-Transfer-Encoding", RFC 1521, December 1993,
605 <URL:http://ds.internic.net/rfc/rfc1521.txt>
607 [6] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
608 Locators (URL)", RFC 1738, December 1994,
609 <URL:http://ds.internic.net/rfc/rfc1738.txt>
611 [7] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
615 Good February 22, 1999 [Page 11]
617 INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
620 Levels", Harvard University, RFC 2119, March 1997,
621 <URL:http://ds.internic.net/rfc/rfc2119.txt>
623 [8] The SLAPD and SLURPD Administrators Guide. University of Michi-
624 gan, April 1996. <URL:
625 http://www.umich.edu/~dirsvcs/ldap/doc/guides/slapd/toc.html>
632 Netscape Communications Corp.
633 501 E. Middlefield Rd.
635 Mountain View, CA 94043, USA
636 Phone: +1 650 937-3825
637 EMail: ggood@netscape.com
639 This Internet Draft expires August 22nd, 1999.
671 Good February 22, 1999 [Page 12]