rfc2849.txt

RFC 的详细文档！

Network Working Group                                             G. Good
Request for Comments: 2849                   iPlanet e-commerce Solutions
Category: Standards Track                                       June 2000


   The LDAP Data Interchange Format (LDIF) - Technical Specification

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

Abstract

   This document describes a file format suitable for describing
   directory information or modifications made to directory information.
   The file format, known as LDIF, for LDAP Data Interchange Format, is
   typically used to import and export directory information between
   LDAP-based directory servers, or to describe a set of changes which
   are to be applied to a directory.

Background and Intended Usage

   There are a number of situations where a common interchange format is
   desirable.  For example, one might wish to export a copy of the
   contents of a directory server to a file, move that file to a
   different machine, and import the contents into a second directory
   server.

   Additionally, by using a well-defined interchange format, development
   of data import tools from legacy systems is facilitated.  A fairly
   simple set of tools written in awk or perl can, for example, convert
   a database of personnel information into an LDIF file. This file can
   then be imported into a directory server, regardless of the internal
   database representation the target directory server uses.

   The LDIF format was originally developed and used in the University
   of Michigan LDAP implementation.  The first use of LDIF was in
   describing directory entries.  Later, the format was expanded to
   allow representation of changes to directory entries.




Good                        Standards Track                     [Page 1]

RFC 2849              LDAP Data Interchange Format             June 2000


   Relationship to the application/directory MIME content-type:

   The application/directory MIME content-type [1] is a general
   framework and format for conveying directory information, and is
   independent of any particular directory service.  The LDIF format is
   a simpler format which is perhaps easier to create, and may also be
   used, as noted, to describe a set of changes to be applied to a
   directory.

   The key words "MUST", "MUST NOT", "MAY", "SHOULD", and "SHOULD NOT"
   used in this document are to be interpreted as described in [7].

Definition of the LDAP Data Interchange Format

   The LDIF format is used to convey directory information, or a
   description of a set of changes made to directory entries.  An LDIF
   file consists of a series of records separated by line separators.  A
   record consists of a sequence of lines describing a directory entry,
   or a sequence of lines describing a set of changes to a directory
   entry.  An LDIF file specifies a set of directory entries, or a set
   of changes to be applied to directory entries, but not both.

   There is a one-to-one correlation between LDAP operations that modify
   the directory (add, delete, modify, and modrdn), and the types of
   changerecords described below ("add", "delete", "modify", and
   "modrdn" or "moddn").  This correspondence is intentional, and
   permits a straightforward translation from LDIF changerecords to
   protocol operations.

Formal Syntax Definition of LDIF

   The following definition uses the augmented Backus-Naur Form
   specified in RFC 2234 [2].

ldif-file                = ldif-content / ldif-changes

ldif-content             = version-spec 1*(1*SEP ldif-attrval-record)

ldif-changes             = version-spec 1*(1*SEP ldif-change-record)

ldif-attrval-record      = dn-spec SEP 1*attrval-spec

ldif-change-record       = dn-spec SEP *control changerecord

version-spec             = "version:" FILL version-number






Good                        Standards Track                     [Page 2]

RFC 2849              LDAP Data Interchange Format             June 2000


version-number           = 1*DIGIT
                           ; version-number MUST be "1" for the
                           ; LDIF format described in this document.

dn-spec                  = "dn:" (FILL distinguishedName /
                                  ":" FILL base64-distinguishedName)

distinguishedName        = SAFE-STRING
                           ; a distinguished name, as defined in [3]

base64-distinguishedName = BASE64-UTF8-STRING
                           ; a distinguishedName which has been base64
                           ; encoded (see note 10, below)

rdn                      = SAFE-STRING
                           ; a relative distinguished name, defined as
                           ; <name-component> in [3]

base64-rdn               = BASE64-UTF8-STRING
                           ; an rdn which has been base64 encoded (see
                           ; note 10, below)

control                  = "control:" FILL ldap-oid        ; controlType
                           0*1(1*SPACE ("true" / "false")) ; criticality
                           0*1(value-spec)                ; controlValue
                           SEP
                           ; (See note 9, below)

ldap-oid                 = 1*DIGIT 0*1("." 1*DIGIT)
                           ; An LDAPOID, as defined in [4]

attrval-spec             = AttributeDescription value-spec SEP

value-spec               = ":" (    FILL 0*1(SAFE-STRING) /
                                ":" FILL (BASE64-STRING) /
                                "<" FILL url)
                           ; See notes 7 and 8, below

url                      = <a Uniform Resource Locator,
                            as defined in [6]>
                                   ; (See Note 6, below)

AttributeDescription     = AttributeType [";" options]
                           ; Definition taken from [4]

AttributeType            = ldap-oid / (ALPHA *(attr-type-chars))

options                  = option / (option ";" options)



Good                        Standards Track                     [Page 3]

RFC 2849              LDAP Data Interchange Format             June 2000


option                   = 1*opt-char

attr-type-chars          = ALPHA / DIGIT / "-"

opt-char                 = attr-type-chars

changerecord             = "changetype:" FILL
                           (change-add / change-delete /
                            change-modify / change-moddn)

change-add               = "add"                SEP 1*attrval-spec

change-delete            = "delete"             SEP

change-moddn             = ("modrdn" / "moddn") SEP
                            "newrdn:" (    FILL rdn /
                                       ":" FILL base64-rdn) SEP
                            "deleteoldrdn:" FILL ("0" / "1")  SEP
                            0*1("newsuperior:"
                            (    FILL distinguishedName /
                             ":" FILL base64-distinguishedName) SEP)

change-modify            = "modify"             SEP *mod-spec

mod-spec                 = ("add:" / "delete:" / "replace:")
                           FILL AttributeDescription SEP
                           *attrval-spec
                           "-" SEP

SPACE                    = %x20
                           ; ASCII SP, space

FILL                     = *SPACE

SEP                      = (CR LF / LF)

CR                       = %x0D
                           ; ASCII CR, carriage return

LF                       = %x0A
                           ; ASCII LF, line feed

ALPHA                    = %x41-5A / %x61-7A
                           ; A-Z / a-z

DIGIT                    = %x30-39
                           ; 0-9




Good                        Standards Track                     [Page 4]

RFC 2849              LDAP Data Interchange Format             June 2000


UTF8-1                   = %x80-BF

UTF8-2                   = %xC0-DF UTF8-1

UTF8-3                   = %xE0-EF 2UTF8-1

UTF8-4                   = %xF0-F7 3UTF8-1

UTF8-5                   = %xF8-FB 4UTF8-1

UTF8-6                   = %xFC-FD 5UTF8-1

SAFE-CHAR                = %x01-09 / %x0B-0C / %x0E-7F
                           ; any value <= 127 decimal except NUL, LF,
                           ; and CR

SAFE-INIT-CHAR           = %x01-09 / %x0B-0C / %x0E-1F /
                           %x21-39 / %x3B / %x3D-7F
                           ; any value <= 127 except NUL, LF, CR,
                           ; SPACE, colon (":", ASCII 58 decimal)
                           ; and less-than ("<" , ASCII 60 decimal)

SAFE-STRING              = [SAFE-INIT-CHAR *SAFE-CHAR]

UTF8-CHAR                = SAFE-CHAR / UTF8-2 / UTF8-3 /
                           UTF8-4 / UTF8-5 / UTF8-6

UTF8-STRING              = *UTF8-CHAR

BASE64-UTF8-STRING       = BASE64-STRING
                           ; MUST be the base64 encoding of a
                           ; UTF8-STRING

BASE64-CHAR              = %x2B / %x2F / %x30-39 / %x3D / %x41-5A /
                           %x61-7A
                           ; +, /, 0-9, =, A-Z, and a-z
                           ; as specified in [5]

BASE64-STRING            = [*(BASE64-CHAR)]


   Notes on LDIF Syntax

      1)  For the LDIF format described in this document, the version
          number MUST be "1". If the version number is absent,
          implementations MAY choose to interpret the contents as an
          older LDIF file format, supported by the University of
          Michigan ldap-3.3 implementation [8].



Good                        Standards Track                     [Page 5]

RFC 2849              LDAP Data Interchange Format             June 2000


      2)  Any non-empty line, including comment lines, in an LDIF file
          MAY be folded by inserting a line separator (SEP) and a SPACE.
          Folding MUST NOT occur before the first character of the line.
          In other words, folding a line into two lines, the first of
          which is empty, is not permitted. Any line that begins with a
          single space MUST be treated as a continuation of the previous
          (non-empty) line. When joining folded lines, exactly one space
          character at the beginning of each continued line must be
          discarded. Implementations SHOULD NOT fold lines in the middle
          of a multi-byte UTF-8 character.

      3)  Any line that begins with a pound-sign ("#", ASCII 35) is a
          comment line, and MUST be ignored when parsing an LDIF file.

      4)  Any dn or rdn that contains characters other than those
          defined as "SAFE-UTF8-CHAR", or begins with a character other
          than those defined as "SAFE-INIT-UTF8-CHAR", above, MUST be
          base-64 encoded.  Other values MAY be base-64 encoded.  Any
          value that contains characters other than those defined as
          "SAFE-CHAR", or begins with a character other than those
          defined as "SAFE-INIT-CHAR", above, MUST be base-64 encoded.
          Other values MAY be base-64 encoded.

      5)  When a zero-length attribute value is to be included directly
          in an LDIF file, it MUST be represented as
          AttributeDescription ":" FILL SEP.  For example, "seeAlso:"
          followed by a newline represents a zero-length "seeAlso"
          attribute value.  It is also permissible for the value
          referred to by a URL to be of zero length.

      6) When a URL is specified in an attrval-spec, the following
          conventions apply:

         a) Implementations SHOULD support the file:// URL format.  The
            contents of the referenced file are to be included verbatim
            in the interpreted output of the LDIF file.
         b) Implementations MAY support other URL formats.  The
            semantics associated with each supported URL will be
            documented in an associated Applicability Statement.

      7)  Distinguished names, relative distinguished names, and
          attribute values of DirectoryString syntax MUST be valid UTF-8
          strings.  Implementations that read LDIF MAY interpret files
          in which these entities are stored in some other character set
          encoding, but implementations MUST NOT generate LDIF content
          which does not contain valid UTF-8 data.





Good                        Standards Track                     [Page 6]

RFC 2849              LDAP Data Interchange Format             June 2000


      8)  Values or distinguished names that end with SPACE SHOULD be
          base-64 encoded.

      9)  When controls are included in an LDIF file, implementations
          MAY choose to ignore some or all of them. This may be
          necessary if the changes described in the LDIF file are being
          sent on an LDAPv2 connection (LDAPv2 does not support
          controls), or the particular controls are not supported by the
          remote server. If the criticality of a control is "true", then
          the implementation MUST either include the control, or MUST
          NOT send the operation to a remote server.

      10) When an attrval-spec, distinguishedName, or rdn is base64-
          encoded, the encoding rules specified in [5] are used with the
          following exceptions:  a) The requirement that base64 output
          streams must be represented as lines of no more than 76
          characters is removed. Lines in LDIF files may only be folded
          according to the folding rules described in note 2, above.  b)
          Base64 strings in [5] may contain characters other than those
          defined in BASE64-CHAR, and are ignored. LDIF does not permit
          any extraneous characters, other than those used for line
          folding.

Examples of LDAP Data Interchange Format

Example 1: An simple LDAP file with two entries

version: 1
dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
cn: Barbara Jensen
cn: Barbara J Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
telephonenumber: [phone]
description: A big sailing fan.

dn: cn=Bjorn Jensen, ou=Accounting, dc=airius, dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
cn: Bjorn Jensen
sn: Jensen
telephonenumber: [phone]




Good                        Standards Track                     [Page 7]