]> git.sur5r.net Git - openldap/blob - doc/man/man5/ldif.5
ITS#7928 fix syncprov abandon cleanup
[openldap] / doc / man / man5 / ldif.5
1 .TH LDIF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" $OpenLDAP$
3 .\" Copyright 1998-2014 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