# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Database Creation and Maintenance Tools
-This section tells you how to create a slapd database from
-scratch, and how to do trouble shooting if you run into
-problems. There are two ways to create a database. First,
-you can create the database on-line using LDAP. With this
-method, you simply start up slapd and add entries using the
-LDAP client of your choice. This method is fine for relatively
-small databases (a few hundred or thousand entries,
-depending on your requirements). This method works for database
-types which support updates.
-
-The second method of database creation is to do it off-line
-using special utilities provided with slapd. This method is
-best if you have many thousands of entries to create, which
-would take an unacceptably long time using the LDAP method,
-or if you want to ensure the database is not accessed while
-it is being created. Note that not all database types support
-these utilitites.
+This section tells you how to create a slapd database from scratch,
+and how to do trouble shooting if you run into problems. There are
+two ways to create a database. First, you can create the database
+on-line using LDAP. With this method, you simply start up slapd
+and add entries using the LDAP client of your choice. This method
+is fine for relatively small databases (a few hundred or thousand
+entries, depending on your requirements). This method works for
+database types which support updates.
+
+The second method of database creation is to do it off-line using
+special utilities provided with slapd. This method is best if you
+have many thousands of entries to create, which would take an
+unacceptably long time using the LDAP method, or if you want to
+ensure the database is not accessed while it is being created. Note
+that not all database types support these utilitites.
H2: Creating a database over LDAP
-With this method, you use the LDAP client of your choice
-(e.g., the ldapadd(1)) to add entries, just like you would
-once the database is created. You should be sure to set the
-following configuration options before starting slapd:
+With this method, you use the LDAP client of your choice (e.g.,
+the {{ldapadd}}(1)) to add entries, just like you would once the
+database is created. You should be sure to set the following
+options in the configuration file before starting {{slapd}}(8).
-E: suffix <dn>
+> suffix <dn>
-As described in the preceding section, this option says what
-entries are to be held by this database. You should set this
-to the DN of the root of the subtree you are trying to create.
-For example
+As described in the {{SECT:General Database Directives}} section,
+this option defines which entries are to be held by this database.
+You should set this to the DN of the root of the subtree you are
+trying to create. For example:
-E: suffix "dc=example, dc=com"
+> suffix "dc=example,dc=com"
-You should be sure to specify a directory where the index
-files should be created:
+You should be sure to specify a directory where the index files
+should be created:
-E: directory <directory>
+> directory <directory>
For example:
-E: directory /usr/local/var/openldap-ldbm
+> directory /usr/local/var/openldap-data
-You need to create this directory with appropriate permissions
-such that slapd can write to it.
+You need to create this directory with appropriate permissions such
+that slapd can write to it.
-You need to make it so you can connect to slapd as directory user
-with permission to add entries. You can configure the directory
-to support a special {{super-user}} or {{root}} user just for
-this purpose. This is done through the following two options
-in the database definition:
+You need to configure slapd so that you can connect to it as a
+directory user with permission to add entries. You can configure
+the directory to support a special {{super-user}} or {{root}} user
+just for this purpose. This is done through the following two
+options in the database definition:
-E: rootdn <dn>
+> rootdn <dn>
For example:
-E: rootdn "cn=Manager, dc=example, dc=com"
-E: rootpw secret
+> rootdn "cn=Manager,dc=example,dc=com"
+> rootpw secret
+
+These options specify a DN and password that can be used to
+authenticate as the {{super-user}} entry of the database (i.e.,
+the entry allowed to do anything). The DN and password specified
+here will always work, regardless of whether the entry named actually
+exists or has the password given. This solves the chicken-and-egg
+problem of how to authenticate and add entries before any entries
+yet exist.
-These options specify a DN and password that can be used
-to authenticate as the {{super-user}} entry of the database (i.e.,
-the entry allowed to do anything). The DN and password
-specified here will always work, regardless of whether the
-entry named actually exists or has the password given. This
-solves the chicken-and-egg problem of how to authenticate
-and add entries before any entries yet exist.
+Finally, you should make sure that the database definition contains
+the index definitions you want:
-Finally, you should make sure that the database definition
-contains the index definitions you want:
+> index {<attrlist> | default} [pres,eq,approx,sub,none]
-E: index {<attrlist> | default} [pres,eq,approx,sub,none]
+For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and
+{{EX:objectclass}} attributes, the following {{EX:index}} directives
+could be used:
-For example, to index the cn, sn, uid and objectclass
-attributes the following index configuration lines could be
-used.
+> index cn,sn,uid pres,eq,approx,sub
+> index objectClass eq
-E: index cn,sn,uid
-E: index objectclass pres,eq
+This would create presence, equality, approximate, and substring
+indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
+an equality index for the {{EX:objectClass}} attribute. Note that
+not all index types are available with all attribute types. See
+{{SECT:The slapd Configuration File}} section for more information
+on this option.
-See Section 4 on the configuration file for more details on
-this option. Once you have configured things to your liking,
-start up slapd, connect with your LDAP client, and start
-adding entries. For example, to add a the organizational entry
-followed by a Postmaster entry using the {{I:ldapadd}} tool, you
-could create an {{TERM:LDIF}} file called {{EX:entries.ldif}} with the
-contents:
+Once you have configured things to your liking, start up slapd,
+connect with your LDAP client, and start adding entries. For
+example, to add an organization entry and an organizational role
+entry using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}}
+file called {{EX:entries.ldif}} with the contents:
-E: dc=example, dc=com
-E: objectClass=dcObject
-E: objectClass=organization
-E: dc=example
-E: o=Example Corporation
-E: description=The Example Corporation
-E:
-E: cn=Postmaster, dc=example, dc=com
-E: objectClass=organizationalRole
-E: cn=Postmaster
-E: description=OpenLDAP Postmaster <Postmaster@example.com>
+> # Organization for Example Corporation
+> dn: dc=example,dc=com
+> objectClass: dcObject
+> objectClass: organization
+> dc: example
+> o: Example Corporation
+> description: The Example Corporation
+>
+> # Organizational Role for Directory Manager
+> dn: cn=Manager,dc=example,dc=com
+> objectClass: organizationalRole
+> cn: Manager
+> description: Directory Manager
-and then use a command like this to actually create the
-entry:
+and then use a command like this to actually create the entry:
-E: ldapadd -f entries.ldif -x -D "cn=Manager, dc=example, dc=com" -w secret
+> ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret
-The above command assumes settings provided in the above
-examples.
+The above command assumes settings provided in the above examples.
H2: Creating a database off-line
-The second method of database creation is to do it off-line,
-using the slapd database tools described below. This method is
-best if you have many thousands of entries to create, which
-would take an unacceptably long time using
-the LDAP method described above. These tools read the
-slapd configuration file and an input file containing a text
-representation of the entries to add. For database types which
-support the tools, they produce the database files directly (otherwise
-you must use the on-line method above). There are several important
-configuration options you will want to be sure and set in the config
-file database definition first:
+The second method of database creation is to do it off-line, using
+the slapd database tools described below. This method is best if
+you have many thousands of entries to create, which would take an
+unacceptably long time to add using the LDAP method described above.
+These tools read the slapd configuration file and an input file
+containing a text representation of the entries to add. For database
+types which support the tools, they produce the database files
+directly (otherwise you must use the on-line method above). There
+are several important configuration options you will want to be
+sure and set in the config file database definition first:
-E: suffix <dn>
+> suffix <dn>
-As described in the preceding section, this option says what
-entries are to be held by this database. You should set this
-to the DN of the root of the subtree you are trying to create.
-For example
+As described in the {{SECT:General Database Directives}} section,
+this option defines which entries are to be held by this database.
+You should set this to the DN of the root of the subtree you are
+trying to create. For example:
-E: suffix "dc=example, dc=com"
+> suffix "dc=example,dc=com"
-You should be sure to specify a directory where the index
-files should be created:
+You should be sure to specify a directory where the index files
+should be created:
-E: directory <directory>
+> directory <directory>
For example:
-E: directory /usr/local/var/openldap-ldbm
+> directory /usr/local/var/openldap-data
-Finally, you need to specify which indexes you want to build.
-This is done by one or more index options.
+Finally, you need to specify which indices you want to build. This
+is done by one or more index options.
-
E: index {<attrlist> | default} [pres,eq,approx,sub,none]
+
> index {<attrlist> | default} [pres,eq,approx,sub,none]
For example:
-E: index cn,sn,uid pres,eq,approx
-E: index objectClass eq
+> index cn,sn,uid pres,eq,approx,sub
+> index objectClass eq
-This would create presence, equality and approximate
-indexes for the cn, sn, and uid attributes and an equality
-index for the objectClass attribute. See the configuration
-file section for more information on this option.
+This would create presence, equality, approximate, and substring
+indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and
+an equality index for the {{EX:objectClass}} attribute. Note that
+not all index types are available with all attribute types. See
+{{SECT:The slapd Configuration File}} section for more information
+on this option.
-H3: The {{EX: slapadd}} program
+H3: The {{EX:slapadd}} program
-Once you've configured things to your liking, you create the
-primary database and associated indexes by running the
-{{slapadd}}(8) program:
+Once you've configured things to your liking, you create the primary
+database and associated indices by running the {{slapadd}}(8)
+program:
-E: slapadd -l <inputfile> -f <slapdconfigfile>
-E: [-d <debuglevel>] [-n <integer>|-b <suffix>]
+> slapadd -l <inputfile> -f <slapdconfigfile>
+> [-d <debuglevel>] [-n <integer>|-b <suffix>]
The arguments have the following meanings:
-E: -l <inputfile>
+> -l <inputfile>
+
+Specifies the {{TERM:LDIF}} input file containing the entries to
+add in text form (described below in the {{SECT:The LDIF text entry
+format}} section).
+
+> -f <slapdconfigfile>
-Specifies the LDIF input file containing the entries to add in
-text form (described below in Section 8.3).
+Specifies the slapd configuration file that tells where to create
+the indices, what indices to create, etc.
-E: -f <slapdconfigfile>
+> -d <debuglevel>
-Specifies the slapd configuration file that tells where to
-create the indexes, what indexes to create, etc.
+Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug
+levels are the same as for slapd. See the {{SECT:Command-Line
+Options}} section in {{SECT:Running slapd}}.
-E: -d <debuglevel>
+> -n <databasenumber>
-Turn on debugging, as specified by {{EX: <debuglevel>}}. The
-debug levels are the same as for slapd (see Section 6.1).
+An optional argument that specifies which database to modify. The
+first database listed in the configuration file is {{EX:1}}, the
+second {{EX:2}}, etc. By default, the first database in the
+configuration file is used. Should not be used in conjunction with
+{{EX:-b}}.
-E: -n <databasenumber>
+> -b <suffix>
-An optional argument that specifies the configuration file
-database for which to build. The first database listed
-is "1", the second "2", etc. By default, the first ldbm database
-in the configuration file is used. Should not be used in
-conjunction with {{EX:-b}}.
+An optional argument that specifies which database to modify. The
+provided suffix is matched against a database {{EX:suffix}} directive
+to determine the database number. Should not be used in conjunction
+with {{EX:-n}}.
-E: -b <suffix>
-An optional argument that specifies the configuration file
-database for which to build. The provided suffix is matched
-against database {{EX:suffix}} to determine the database
-number. Should not be used in conjunction with {{EX:-n}}.
+H3: The {{EX:slapindex}} program
+Sometimes it may be necessary to regenerate indices (such as after
+modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8)
+program. {{slapindex}} is invoked like this
-H3: The {{EX: ldif2index}} program
+> slapindex -f <slapdconfigfile>
+> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
-Sometimes it may be necessary to regenerate indices (such
-as after modifying {{slapd.conf}}(5)). This is possible using
-the {{slapindex}}(8) program. {{EX: slapindex}} is invoked
-like this
+Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options
+are the same as for the {{slapadd}}(1) program. {{slapindex}}
+rebuilds all indices based upon the current database contents.
-E: slapindex -f <slapdconfigfile>
-E: [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
-Where the -f, -d, -n and -b options are the same as for the
-{{slapadd}}(1) program. slapindex rebuilds all indices based
-upon the current database contents.
+H3: The {{EX:slapcat}} program
+The {{EX:slapcat}} program is used to dump the database to an
+{{TERM:LDIF}} file. This can be useful when you want to make a
+human-readable backup of your database or when you want to edit
+your database off-line. The program is invoked like this:
-H3: The {{EX: slapcat}} program
+> slapcat -l <filename> -f <slapdconfigfile>
+> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
-The {{EX: slapcat}} program is dump the database to a {{TERM:LDIF}}
-file. This can be useful when you want to make a human-readable
-backup of your database or for editing your database off-line.
-The program is invoked like this:
+where {{EX:-n}} or {{EX:-b}} is used to select the database in the
+{{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding
+{{TERM:LDIF}} output is written to standard output or to the file
+specified using the {{EX:-l}} option.
-E: slapcat -l <filename> -f <slapdconfigfile>
-E: [-d <debuglevel>] [-n <databasenumber>|-b <suffix>]
-where -n or -b is used to select the database in the slapd.conf(5)
-specified using -f. The corresponding LDIF output is written to
-standard output or to the file specified using the -l option.
+!if 0
+H3: The {{EX:ldif}} program
+The {{ldif}}(1) program is used to convert arbitrary data values
+to {{TERM:LDIF}} format. This can be useful when writing a program
+or script to create the LDIF file you will feed into the {{slapadd}}(8)
+or {{ldapadd}}(1) program, or when writing a SHELL backend.
+{{ldif}}(1) takes an attribute description as an argument and reads
+the attribute value(s) from standard input. It produces the LDIF
+formatted attribute line(s) on standard output. The usage is:
-H3: The {{EX: ldif}} program
+> ldif [-b] <attrdesc>
-The ldif program is used to convert arbitrary data values to
-LDIF format. This can be useful when writing a program or
-script to create the LDIF file you will feed into the ldif2ldbm
-program, or when writing a SHELL backend. ldif takes an
-attribute name as an argument, and reads the attribute
-value(s) from standard input. It produces the LDIF formatted
-attribute line(s) on standard output. The usage is:
+where {{EX:<attrdesc>}} is an attribute description. Without the
+{{EX-b}} option, the {{ldif}} program will consider each line of
+standard input to be a separate value of the attribute.
-E: ldif [-b] <attrname>
+> ldif description << EOF
+> leading space
+> # leading hash mark
+> EOF
-where {{EX: <attrname>}} is the name of the attribute. Without the
--b option, ldif considers each line of standard input to be a
-separate value of the attribute.
+The {{EX:-b}} option can be used to force the {{ldif}} program to
+interpret its input as a single raw binary value. This option is
+useful when converting binary data such as a {{EX:jpegPhoto}} or
+{{EX:audio}} attribute. For example:
-The -b option can be used to force ldif to interpret its input
-as a single raw binary value. This option is useful when
-converting binary data such as a {{EX: jpegPhoto}} or {{EX: audio}}
-attribute.
+> ldif -b jpegPhoto < photo.jpeg
+!endif
H2: The LDIF text entry format
-The LDAP Data Interchange Format (LDIF) is used to
-represent LDAP entries in a simple text format. The basic
-form of an entry is:
+The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries
+in a simple text format. This section provides a brief description
+of the LDIF entry format which complements {{ldif}}(5) and the
+technical specification {{REF:RFC2849}}.
+
+The basic form of an entry is:
+
+> # comment
+> dn: <distinguished name>
+> <attrdesc>: <attrvalue>
+> <attrdesc>: <attrvalue>
+>
+> ...
+
+Lines starting with a '{{EX:#}}' character are comments. An
+attribute description may be a simple attribute type like {{EX:cn}}
+or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated
+with an attribute type) or may include options such as {{EX:cn;lang_en_US}}
+or {{EX:userCertificate;binary}}.
-E: [<id>]
-E: dn: <distinguished name>
-E: <attrtype>: <attrvalue>
-E: <attrtype>: <attrvalue>
-E:
-E: ...
+A line may be continued by starting the next line with a {{single}}
+space or tab character. For example:
-where {{EX: <id>}} is the optional entry ID (a positive decimal
-number). Normally, you would not supply the {{EX: <id>}}, allowing
-the database creation tools to do that for you. The ldbmcat
-program, however, produces an LDIF format that includes
-{{EX: <id>}} so that new indexes created will be consistent.
+> dn: cn=Barbara J Jensen,dc=example,dc=
+> com
+> cn: Barbara J
+> Jensen
-A line may be continued by starting the next line with a
-single space or tab character. e.g.,
+is equivalent to:
-E: dn: cn=Barbara J Jensen, dc=example, dc=com
+> dn: cn=Barbara J Jensen,dc=example,dc=com
+> cn: Barbara J Jensen
Multiple attribute values are specified on separate lines. e.g.,
-E: cn: Barbara J Jensen
-E: cn: Babs Jensen
-
-If an {{EX: <attrvalue>}} contains a non-printing character, or
-begins with a space or a colon `:', the {{EX: <attrtype>}} is followed
-by a double colon and the value is encoded in base 64
-notation. e.g., the value " begins with a space" would be
-encoded like this:
-
-E: cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
-
-Multiple entries within the same LDIF file are separated by
-blank lines. Here's an example of an LDIF file containing
-three entries.
-
-E: dn: cn=Barbara J Jensen, dc=example, dc=com
-E: cn: Barbara J Jensen
-E: cn: Babs Jensen
-E: objectclass: person
-E: sn: Jensen
-E:
-E: dn: cn=Bjorn J Jensen, dc=example, dc=com
-E: cn: Bjorn J Jensen
-E: cn: Bjorn Jensen
-E: objectclass: person
-E: sn: Jensen
-E:
-E: dn: cn=Jennifer J Jensen, dc=example, dc=com
-E: cn: Jennifer J Jensen
-E: cn: Jennifer Jensen
-E: objectclass: person
-E: sn: Jensen
-E: jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
-E: A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
-E: ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
-E:
-E: ...
-
-Notice that the {{EX: jpegPhoto}} in Jennifer Jensen's entry is
-encoded using base 64. The {{EX: ldif}} program (described in
-Section 8.2.6) can be used to produce the LDIF format.
-
-Note: Trailing spaces are not trimmed from values in an
-LDIF file. Nor are multiple internal spaces compressed. If
-you don't want them in your data, don't put them there.
+> cn: Barbara J Jensen
+> cn: Babs Jensen
+
+If an {{EX:<attrvalue>}} contains non-printing characters or begins
+with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'),
+the {{EX:<attrdesc>}} is followed by a double colon and the base64
+encoding of the value. For example, the value "{{EX: begins with
+a space}}" would be encoded like this:
+
+> cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
+
+You can also specify a {{TERM:URL}} containing the attribute value.
+For example, the following specifies the {{EX:jpegPhoto}} value
+should be obtained from the file {{F:/path/to/file.jpeg}}.
+
+> cn:< file:///path/to/file.jpeg
+
+Multiple entries within the same LDIF file are separated by blank
+lines. Here's an example of an LDIF file containing three entries.
+
+> # Barbara's Entry
+> dn: cn=Barbara J Jensen,dc=example,dc=com
+> cn: Barbara J Jensen
+> cn: Babs Jensen
+> objectClass: person
+> sn: Jensen
+>
+> # Bjorn's Entry
+> dn: cn=Bjorn J Jensen,dc=example,dc=com
+> cn: Bjorn J Jensen
+> cn: Bjorn Jensen
+> objectClass: person
+> sn: Jensen
+> # Base64 encoded JPEG photo
+> jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
+> A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
+> ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
+>
+> # Jennifer's Entry
+> dn: cn=Jennifer J Jensen,dc=example,dc=com
+> cn: Jennifer J Jensen
+> cn: Jennifer Jensen
+> objectClass: person
+> sn: Jensen
+> # JPEG photo from file
+> jpegPhoto:< file:///path/to/file.jpeg
+
+Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded
+and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the
+location indicated by the URL.
+
+Note: Trailing spaces are not trimmed from values in an LDIF file.
+Nor are multiple internal spaces compressed. If you don't want them
+in your data, don't put them there.
projects / openldap / blobdiff