X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fdbtools.sdf;h=672ba0fdb87076915f318b93de004e1b9d4261a4;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=bf191347a1b862b77bafe70109b97873e2e9594d;hpb=77932a32aea4e4562385db50dacf275bf3329696;p=openldap diff --git a/doc/guide/admin/dbtools.sdf b/doc/guide/admin/dbtools.sdf index bf191347a1..672ba0fdb8 100644 --- a/doc/guide/admin/dbtools.sdf +++ b/doc/guide/admin/dbtools.sdf @@ -1,171 +1,175 @@ # $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). > suffix -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: -> 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: > directory For example: -> 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: > rootdn > rootpw For example: -> rootdn "cn=Manager, dc=example, dc=com" +> 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 { | default} [pres,eq,approx,sub,none] -For example, to index the cn, sn, uid and objectclass -attributes the following index configuration lines could be -used. - -> index cn,sn,uid -> index objectclass pres,eq - -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: - -> dc=example, dc=com -> objectClass=dcObject -> objectClass=organization -> dc=example -> o=Example Corporation -> description=The Example Corporation +For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and +{{EX:objectclass}} attributes, the following {{EX:index}} directives +could be used: + +> index cn,sn,uid pres,eq,approx,sub +> index objectClass 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. + +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: + +> # Organization for Example Corporation +> dn: dc=example,dc=com +> objectClass: dcObject +> objectClass: organization +> dc: example +> o: Example Corporation +> description: The Example Corporation > -> cn=Postmaster, dc=example, dc=com -> objectClass=organizationalRole -> cn=Postmaster -> description=OpenLDAP Postmaster +> # 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: > 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: > suffix -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: -> 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: > directory For example: -> 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. > index { | default} [pres,eq,approx,sub,none] For example: -> index cn,sn,uid pres,eq,approx +> 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 -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: > slapadd -l -f > [-d ] [-n |-b ] @@ -174,98 +178,106 @@ The arguments have the following meanings: > -l -Specifies the LDIF input file containing the entries to add in -text form (described below in Section 8.3). +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 -Specifies the slapd configuration file that tells where to -create the indexes, what indexes to create, etc. +Specifies the slapd configuration file that tells where to create +the indices, what indices to create, etc. > -d -Turn on debugging, as specified by {{EX:}}. The -debug levels are the same as for slapd (see Section 6.1). +Turn on debugging, as specified by {{EX:}}. The debug +levels are the same as for slapd. See the {{SECT:Command-Line +Options}} section in {{SECT:Running slapd}}. > -n -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 +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}}. > -b -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}}. +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}}. 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. {{EX:slapindex}} is invoked -like this +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 > slapindex -f > [-d ] [-n |-b ] -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. +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. H3: The {{EX:slapcat}} program -The {{EX:slapcat}} program is used to 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: +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: > slapcat -l -f > [-d ] [-n |-b ] -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. +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. +!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 descriptin 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: +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: > ldif [-b] -where {{EX:}} is an attribute description. Without the -b -option, ldif considers each line of standard input to be a separate -value of the attribute. +where {{EX:}} 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. > ldif description << EOF > leading space > # leading hash mark > EOF -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. For example: +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: > 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: @@ -274,23 +286,23 @@ entries in a simple text format. The basic form of an entry is: > > ... -Lines starting with '{{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}}. +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}}. -A line may be continued by starting the next line with a -{{single}} space or tab character. For example: +A line may be continued by starting the next line with a {{single}} +space or tab character. For example: -> dn: cn=Barbara J Jensen, dc=example, dc= +> dn: cn=Barbara J Jensen,dc=example,dc= > com > cn: Barbara J > Jensen is equivalent to: -> 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., @@ -298,50 +310,55 @@ Multiple attribute values are specified on separate lines. e.g., > cn: Barbara J Jensen > cn: Babs Jensen -If an {{EX:}} contains a non-printing character, or -begins with a space or a colon '{{EX::}}', the {{EX:}} is followed -by a double colon and the value is encoded in base 64 -notation. e.g., the value {{EX:" begins with a space"}} would be -encoded like this: +If an {{EX:}} contains non-printing characters or begins +with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'), +the {{EX:}} 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= -Multiple entries within the same LDIF file are separated by -blank lines. Here's an example of an LDIF file containing -three entries. +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. -> # First Entry -> dn: cn=Barbara J Jensen, dc=example, dc=com +> # Barbara's Entry +> dn: cn=Barbara J Jensen,dc=example,dc=com > cn: Barbara J Jensen > cn: Babs Jensen -> objectclass: person +> objectClass: person > sn: Jensen > -> # Second Entry -> dn: cn=Bjorn J Jensen, dc=example, dc=com +> # Bjorn's Entry +> dn: cn=Bjorn J Jensen,dc=example,dc=com > cn: Bjorn J Jensen > cn: Bjorn Jensen -> objectclass: person +> objectClass: person > sn: Jensen +> # Base64 encoded JPEG photo +> jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD +> A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ +> ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG > -> # Third Entry -> dn: cn=Jennifer J Jensen, dc=example, dc=com +> # Jennifer's Entry +> dn: cn=Jennifer J Jensen,dc=example,dc=com > cn: Jennifer J Jensen > cn: Jennifer Jensen -> objectclass: person +> objectClass: person > sn: Jensen -> # Base64 encoded JPEG photo -> jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD -> A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ -> ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG - -Notice that the {{EX:jpegPhoto}} in Jennifer's entry is -encoded using base 64. The {{ldif}}(1) program (described in -{{SECT:The {{EX:ldif}} program}} section above) can be used to -produce an attribute-description/base64-value pair suitable for -inclusion in an LDIF file. - -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. +> # 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.