git.sur5r.net Git - openldap/blob - doc/man/man5/ldif.5

   1 .TH LDIF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2015 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldif \- LDAP Data Interchange Format
   7 .SH DESCRIPTION
   8 The LDAP Data Interchange Format (LDIF) is used to represent LDAP
   9 entries and change records in text form. LDAP tools, such as
  10 .BR ldapadd (1)
  11 and
  12 .BR ldapsearch (1),
  13 read and write LDIF entry
  14 records.
  15 .BR ldapmodify (1)
  16 reads LDIF change records.
  17 .LP
  18 This manual page provides a basic description of LDIF.  A
  19 formal specification of LDIF is published in RFC 2849.
  20 .SH ENTRY RECORDS
  21 .LP
  22 LDIF entry records are used to represent directory entries.  The basic
  23 form of an entry record is:
  24 .LP
  25 .nf
  26 .ft tt
  27         dn: <distinguished name>
  28         <attrdesc>: <attrvalue>
  29         <attrdesc>: <attrvalue>
  30         <attrdesc>:: <base64-encoded-value>
  31         <attrdesc>:< <URL>
  32         ...
  33 .ft
  34 .fi
  35 .LP
  36 The value may be specified as UTF-8 text or as base64 encoded data,
  37 or a URI may be provided to the location of the attribute value.
  38 .LP
  39 A line may be continued by starting the next line with a single space
  40 or tab, e.g.,
  41 .LP
  42 .nf
  43 .ft tt
  44         dn: cn=Barbara J Jensen,dc=exam
  45          ple,dc=com
  46 .ft
  47 .fi
  48 .LP
  49 Lines beginning with a sharp sign ('#') are ignored.
  50 .LP
  51 Multiple attribute values are specified on separate lines, e.g.,
  52 .LP
  53 .nf
  54 .ft tt
  55         cn: Barbara J Jensen
  56         cn: Babs Jensen
  57 .ft
  58 .fi
  59 .LP
  60 If an value contains a non-printing character, or begins
  61 with a space or a colon ':', the <attrtype> is followed by a
  62 double colon and the value is encoded in base 64 notation. e.g.,
  63 the value " begins with a space" would be encoded like this:
  64 .LP
  65 .nf
  66 .ft tt
  67         cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
  68 .ft
  69 .fi
  70 .LP
  71 If the attribute value is located in a file, the <attrtype> is
  72 followed by a ':<' and a file: URI.  e.g., the value contained
  73 in the file /tmp/value would be listed like this:
  74 .LP
  75 .nf
  76 .ft tt
  77         cn:< file:///tmp/value
  78 .ft
  79 .fi
  80 Other URI schemes (ftp,http) may be supported as well.
  81 .LP
  82 Multiple entries within the same LDIF file are separated by blank
  83 lines.
  84 .SH ENTRY RECORD EXAMPLE
  85 Here is an example of an LDIF file containing three entries.
  86 .LP
  87 .nf
  88 .ft tt
  89         dn: cn=Barbara J Jensen,dc=example,dc=com
  90         cn: Barbara J Jensen
  91         cn: Babs Jensen
  92         objectclass: person
  93         description:< file:///tmp/babs
  94         sn: Jensen
  95
  96         dn: cn=Bjorn J Jensen,dc=example,dc=com
  97         cn: Bjorn J Jensen
  98         cn: Bjorn Jensen
  99         objectclass: person
 100         sn: Jensen
 101
 102         dn: cn=Jennifer J Jensen,dc=example,dc=com
 103         cn: Jennifer J Jensen
 104         cn: Jennifer Jensen
 105         objectclass: person
 106         sn: Jensen
 107         jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
 108          A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
 109          ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
 110         ...
 111 .ft
 112 .fi
 113 .LP
 114 Note that the description in Barbara Jensen's entry is
 115 read from file:///tmp/babs and the jpegPhoto in Jennifer
 116 Jensen's entry is encoded using base 64.
 117 .SH CHANGE RECORDS
 118 LDIF change records are used to represent directory change requests.
 119 Each change record starts with line indicating the distinguished
 120 name of the entry being changed:
 121 .LP
 122 .nf
 123         dn: <distinguishedname>
 124 .fi
 125 .LP
 126 .nf
 127         changetype: <[modify|add|delete|modrdn]>
 128 .fi
 129 .LP
 130 Finally, the change information itself is given, the format of which
 131 depends on what kind of change was specified above.  For a \fIchangetype\fP
 132 of \fImodify\fP, the format is one or more of the following:
 133 .LP
 134 .nf
 135         add: <attributetype>
 136         <attrdesc>: <value1>
 137         <attrdesc>: <value2>
 138         ...
 139         \-
 140 .fi
 141 .LP
 142 Or, for a replace modification:
 143 .LP
 144 .nf
 145         replace: <attributetype>
 146         <attrdesc>: <value1>
 147         <attrdesc>: <value2>
 148         ...
 149         \-
 150 .fi
 151 .LP
 152 If no \fIattributetype\fP lines are given to replace,
 153 the entire attribute is to be deleted (if present).
 154 .LP
 155 Or, for a delete modification:
 156 .LP
 157 .nf
 158         delete: <attributetype>
 159         <attrdesc>: <value1>
 160         <attrdesc>: <value2>
 161         ...
 162         \-
 163 .fi
 164 .LP
 165 If no \fIattributetype\fP lines are given to delete,
 166 the entire attribute is to be deleted.
 167 .LP
 168 For a \fIchangetype\fP of \fIadd\fP, the format is:
 169 .LP
 170 .nf
 171         <attrdesc1>: <value1>
 172         <attrdesc1>: <value2>
 173         ...
 174         <attrdescN>: <value1>
 175         <attrdescN>: <value2>
 176 .fi
 177 .LP
 178 For a \fIchangetype\fP of \fImodrdn\fP or \fImoddn\fP,
 179 the format is:
 180 .LP
 181 .nf
 182         newrdn: <newrdn>
 183         deleteoldrdn: 0 | 1
 184         newsuperior: <DN>
 185 .fi
 186 .LP
 187 where a value of 1 for deleteoldrdn means to delete the values
 188 forming the old rdn from the entry, and a value of 0 means to
 189 leave the values as non-distinguished attributes in the entry.
 190 The newsuperior line is optional and, if present, specifies the
 191 new superior to move the entry to.
 192 .LP
 193 For a \fIchangetype\fP of \fIdelete\fP, no additional information
 194 is needed in the record.
 195 .LP
 196 Note that attribute values may be presented using base64 or in
 197 files as described for entry records.  Lines in change records
 198 may be continued in the manner described for entry records as
 199 well.
 200 .SH CHANGE RECORD EXAMPLE
 201 The following sample LDIF file contains a change record
 202 of each type of change.
 203 .LP
 204 .nf
 205         dn: cn=Babs Jensen,dc=example,dc=com
 206         changetype: add
 207         objectclass: person
 208         objectclass: extensibleObject
 209         cn: babs
 210         cn: babs jensen
 211         sn: jensen
 212
 213         dn: cn=Babs Jensen,dc=example,dc=com
 214         changetype: modify
 215         add: givenName
 216         givenName: Barbara
 217         givenName: babs
 218         \-
 219         replace: description
 220         description: the fabulous babs
 221         \-
 222         delete: sn
 223         sn: jensen
 224         \-
 225
 226         dn: cn=Babs Jensen,dc=example,dc=com
 227         changetype: modrdn
 228         newrdn: cn=Barbara J Jensen
 229         deleteoldrdn: 0
 230         newsuperior: ou=People,dc=example,dc=com
 231
 232         dn: cn=Barbara J Jensen,ou=People,dc=example,dc=com
 233         changetype: delete
 234 .fi
 235
 236 .SH INCLUDE STATEMENT
 237 The LDIF parser has been extended to support an
 238 .B include
 239 statement for referencing other LDIF files.  The
 240 .B include
 241 statement must be separated from other records by a blank line.
 242 The referenced file is specified using a file: URI and all of its
 243 contents are incorporated as if they were part of the original
 244 LDIF file. As above, other URI schemes may be supported. For example:
 245 .LP
 246 .nf
 247         dn: dc=example,dc=com
 248         objectclass: domain
 249         dc: example
 250
 251         include: file:///tmp/example.com.ldif
 252
 253         dn: dc=example,dc=org
 254         objectclass: domain
 255         dc: example
 256 .fi
 257 This feature is not part of the LDIF specification in RFC 2849 but
 258 is expected to appear in a future revision of this spec. It is supported
 259 by the
 260 .BR ldapadd (1),
 261 .BR ldapmodify (1),
 262 and
 263 .BR slapadd (8)
 264 commands.
 265
 266 .SH SEE ALSO
 267 .BR ldap (3),
 268 .BR ldapsearch (1),
 269 .BR ldapadd (1),
 270 .BR ldapmodify (1),
 271 .BR slapadd (8),
 272 .BR slapcat (8),
 273 .BR slapd\-ldif (5).
 274 .LP
 275 "LDAP Data Interchange Format," Good, G., RFC 2849.
 276 .SH ACKNOWLEDGEMENTS
 277 .so ../Project