X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fdbtools.sdf;h=672ba0fdb87076915f318b93de004e1b9d4261a4;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=d296f30a89a186e5c89af9cd090d34d6324eef76;hpb=3da5981adc90e04185c972edb00187449ffc41a0;p=openldap diff --git a/doc/guide/admin/dbtools.sdf b/doc/guide/admin/dbtools.sdf index d296f30a89..672ba0fdb8 100644 --- a/doc/guide/admin/dbtools.sdf +++ b/doc/guide/admin/dbtools.sdf @@ -1,710 +1,364 @@ -# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved. +# $OpenLDAP$ +# 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). +H1: Database Creation and Maintenance Tools -The second method of database creation is to do it off-line, -using the index generation tools. 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. +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 +options in the configuration file before starting {{slapd}}(8). +> suffix -With this method, you use the LDAP client of your choice -(e.g., the ldapadd(1) tool) 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: - -E: 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: -E: suffix "dc=OpenLDAP, dc=org" +> 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 For example: -E: directory /usr/local/openldap/slapd - -You need to make it so you can connect to slapd as -somebody with permission to add entries. This is done -through the following two options in the database definition: - -E: rootdn -E: rootpw - -These options specify a DN and password that can be used -to authenticate as the "superuser" 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: - -E: 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. - -E: index cn,sn,uid -E: index objectclass pres,eq -E: index default none - -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 a file called {{EX:/tmp/newentry}} with the contents: - - -E: dc=OpenLDAP, dc=org -E: objectClass=dcObject -E: objectClass=organization -E: dc=OpenLDAP -E: o=OpenLDAP -E: o=OpenLDAP Project -E: o=OpenLDAP Foundation -E: description=The OpenLDAP Foundation -E: description=The OpenLDAP Project -E: -E: cn=Postmaster, dc=OpenLDAP, dc=org -E: objectClass=organizationalRole -E: cn=Postmaster -E: description=OpenLDAP Postmaster - -and then use a command like this to actually create the -entry: - -E: ldapadd -f /tmp/newentry -D \ - "cn=Manager, dc=OpenLDAP, dc=org" -w secret - -The above command assumes that you have set {{EX: rootdn}} to -"cn=Manager, dc=OpenLDAP, dc=org" and {{EX: rootpw}} -to "secret". - -H2: Creating a database off-line - -The second method of database creation is to do it off-line, -using the index generation 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. They produce the LDBM -index files directly. There are several important configuration -options you will want to be sure and set in the config file -database definition first: - -E: suffix +> directory /usr/local/var/openldap-data -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 +You need to create this directory with appropriate permissions such +that slapd can write to it. -E: suffix "dc=OpenLDAP, dc=org" +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: -You should be sure to specify a directory where the index -files should be created: - -E: directory +> rootdn +> rootpw For example: -E: directory /usr/local/var/openldap - -Next, you probably want to increase the size of the in-core -cache used by each open index file. For best performance -during index creation, the entire index should fit in memory. If -your data is too big for this, or your memory too small, you -can still make it pretty big and let the paging system do the -work. This size is set with the following option: +> rootdn "cn=Manager,dc=example,dc=com" +> rootpw secret -E: dbcachesize - -For example: +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. -E: dbcachesize 50000000 +Finally, you should make sure that the database definition contains +the index definitions you want: -This would create a cache 50 MB big, which is pretty big (at -U-M, our database has about 125K entries, and our biggest -index file is about 45 MB). Experiment with this number a bit, -and the degree of parallelism (explained below), to see what -works best for your system. Remember to turn this number -back down once your index files are created and before you -run slapd. +> index { | default} [pres,eq,approx,sub,none] -Finally, you need to specify which indexes you want to build. -This is done by one or more index options. +For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and +{{EX:objectclass}} attributes, the following {{EX:index}} directives +could be used: -E: index { | default} [pres,eq,approx,sub,none] +> index cn,sn,uid pres,eq,approx,sub +> index objectClass eq -For example: +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. -E: index cn,sn,uid pres,eq,approx -E: index default none +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: -This would create presence, equality and approximate -indexes for the cn, sn, and uid attributes, and no indexes for -any other attributes. See the configuration file section for -more information on this option. +> # 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 -H3: The {{EX: ldif2ldbm}} program +and then use a command like this to actually create the entry: -Once you've configured things to your liking, you create the -indexes by running the ldif2ldbm program: +> ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret -E: ldif2ldbm -i -f -E: [-d ] [-j ] -E: [-n ] [-e ] +The above command assumes settings provided in the above examples. -The arguments have the following meanings: -E: -i +H2: Creating a database off-line -Specifies the LDIF input file containing the entries to add in -text form (described below in Section 8.3). +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: -f +> suffix -Specifies the slapd configuration file that tells where to -create the indexes, what indexes to create, etc. +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: -d +> suffix "dc=example,dc=com" -Turn on debugging, as specified by {{EX: }}. The -debug levels are the same as for slapd (see Section 6.1). +You should be sure to specify a directory where the index files +should be created: -E: -j +> directory -An optional argument that specifies that at most {{EX: }} -processes should be started in parallel when building the -indexes. The default is 1. If set to a value greater than one, -{{I: ldif2ldbm}} will create at most that many subprocesses at a -time when building the indexes. A separate subprocess is -created to build each attribute index. Running these -processes in parallel can speed things up greatly, but -beware of creating too many processes, all competing for -memory and disk resources. +For example: -E: -n +> directory /usr/local/var/openldap-data -An optional argument that specifies the configuration file -database for which to build indices. The first database listed -is "1", the second "2", etc. By default, the first ldbm database -in the configuration file is used. +Finally, you need to specify which indices you want to build. This +is done by one or more index options. -E: -e +> index { | default} [pres,eq,approx,sub,none] -An optional argument that specifies the directory where -{{EX: ldif2ldbm}} can find the other database conversion tools it -needs to execute ({{EX: ldif2index}} and friends). The default is the -installation {{EX: ETCDIR}}. +For example: -The next sections describe the programs invoked by -{{I: ldif2ldbm}} when it is building indexes. Normally, these -programs are invoked for you, but occasionally you may -want to invoke them yourself. +> 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. +H3: The {{EX:slapadd}} program -H3: The {{EX: ldif2index}} program +Once you've configured things to your liking, you create the primary +database and associated indices by running the {{slapadd}}(8) +program: -Sometimes it may be necessary to create a new attribute -index file without disturbing the rest of the database. This is -possible using the {{EX: ldif2index}} program. {{EX: ldif2index}} is invoked -like this +> slapadd -l -f +> [-d ] [-n |-b ] -E: ldif2index -i -f -E: [-d ] [-n ] +The arguments have the following meanings: -Where the -i, -f, -d, and -n options are the same as for the -{{I: ldif2ldbm}} program. {{EX: }} is the attribute to build an index for. -Which indexes are built (e.g., equality, substring, etc.) is -controlled by the corresponding index line in the slapd -configuration file. +> -l -You can use the ldbmcat program to create a suitable LDIF -input file from an existing LDBM database. +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 indices, what indices to create, etc. -H3: The {{EX: ldif2id2entry}} program +> -d -The {{EX: ldif2id2entry}} program is normally invoked from {{EX: ldif2ldbm}}. -It is used to convert an LDIF text file into an {{EX: id2entry}} index. -It is unlikely that you would need to invoke it yourself, but if -you do it works like this +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}}. -E: ldif2id2entry -i -f -E: [-d ] [-n ] +> -n -The arguments are the same as for the {{EX: ldif2ldbm}} program. +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 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: ldif2id2children}} program -The {{EX: ldif2id2children}} program is normally invoked from -{{EX: ldif2ldbm}}. It is used to convert an LDIF text file into -{{EX: id2children}} and {{EX: dn2id}} indexes. Occasionally, it may be -necessary to run this program yourself, for example if one of -these indexes has become corrupted. {{EX: ldif2id2children}} is -invoked like this +H3: The {{EX:slapindex}} program -E: ldif2id2children -i -f -E: [-d ] [-n ] +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 -The arguments are the same as for the {{EX: ldif2ldbm}} program. -You can use the ldbmcat program to create a suitable LDIF -input file from an existing LDBM database. +> slapindex -f +> [-d ] [-n |-b ] +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: ldbmcat}} program +H3: The {{EX:slapcat}} program -The {{EX: ldbmcat}} program is used to convert an {{EX: id2entry}} index -back into its LDIF text format. This can be useful when you -want to make a human-readable backup of your database, -or as an intermediate step in creating a new index using the -{{EX: ldif2index}} program. 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: -E: ldbmcat [-n] +> slapcat -l -f +> [-d ] [-n |-b ] -where {{EX: }} is the name of the {{EX: id2entry}} index file. The -corresponding LDIF output is written to standard output. +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. -The -n option can be used to prevent the printing of entry -IDs in the LDIF format. If you are creating an LDIF format for -use as input to {{EX: ldif2index}} or anything by {{EX: ldif2ldbm}}, you -should not use the -n option (because the entry IDs must -match those already in the id2entry file). If you are just -making a backup of your data, you can use the -n option to -save space. +!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] -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:}} 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] +> ldif description << EOF +> leading space +> # leading hash mark +> EOF -where {{EX: }} 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: - -E: [] -E: dn: -E: : -E: : -E: -E: ... - -where {{EX: }} is the optional entry ID (a positive decimal -number). Normally, you would not supply the {{EX: }}, allowing -the database creation tools to do that for you. The ldbmcat -program, however, produces an LDIF format that includes -{{EX: }} so that new indexes created will be consistent. - -A line may be continued by starting the next line with a -single space or tab character. e.g., - -E: dn: cn=Barbara J Jensen, dc=OpenLDAP, dc=org - -Multiple attribute values are specified on separate lines. e.g., - -E: cn: Barbara J Jensen -E: cn: Babs Jensen - -If an {{EX: }} contains a non-printing character, or -begins with a space or a colon `:', the {{EX: }} 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=OpenLDAP, dc=org -E: cn: Barbara J Jensen -E: cn: Babs Jensen -E: objectclass: person -E: sn: Jensen -E: -E: -E: dn: cn=Bjorn J Jensen, dc=OpenLDAP, dc=org -E: cn: Bjorn J Jensen -E: cn: Bjorn Jensen -E: objectclass: person -E: sn: Jensen -E: -E: dn: cn=Jennifer J Jensen, dc=OpenLDAP, dc=org -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. +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: -H2: Converting from QUIPU EDB format to LDIF format +> # comment +> dn: +> : +> : +> +> ... -If you have directory data that is or was held in a QUIPU -DSA (available as part of the ISODE package), you will want -to convert the EDB files used by QUIPU into an LDIF file. -The edb2ldif program is provided to do most of the -conversion for you. Once you have an LDIF file, you should -follow the steps outlined in section 6.2 above to build an -LDBM database for slapd. +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: +> dn: cn=Barbara J Jensen,dc=example,dc= +> com +> cn: Barbara J +> Jensen -H3: The {{EX: edb2ldif}} program +is equivalent to: -The edb2ldif program is invoked like this: - -E: edb2ldif [-d] [-v] [-r] [-o] [-b ] -E: [-a ] [-f ] -E: [-i ] [] - -The LDIF data is written to standard output. The arguments -have the following meanings: - -E: -d - -This option enables some debugging output on standard -error. - -E: -v - -Enable verbose mode that writes status information to -standard error, such as which EDB file is being processed, -how many entries have been converted so far, etc. - -E: -r - -Recurse through child directories, processing all EDB files -found. - -E: -o - -Cause local .add file definitions to override the global addfile -(see -a below) - -E: -b - -Specify the Distinguished Name that all EDB file entries -appear below. - -E: -a - -The LDIF information contained in this file will be appended -to each entry. - -E: -f - -Specify a single directory where all file-based attributes -(typically sounds and images) can be found. If this option is -not given, file attributes are assumed to be located in the -same directory as the EDB file that refers to them. - -E: -i - -Specify an attribute that should not be converted. You can -include as many -i flags as necessary. - -E: - -Specify a particular EDB file (or files) to read data from. By -default, the EDB.root (if it exists) and EDB files in the current -directory are used. - -When {{EX: edb2ldif}} is invoked, it will also look for files named -.add in the directories where EDB files are found and append -the contents of the .add file to each entry. Typically, this -feature is used to include inherited attribute values (e.g., -{{EX: objectClass}}) that do not appear in the EDB files. - - - -H3: Step-by-step EDB to LDIF conversion - -The basic steps to follow when converting your EDB format -data to an LDIF file are: - -^ Locate the directory at the top of the EDB file hierarchy -.that your QUIPU DSA masters. The EDB file located there -.should contain the entries for the first level of your -.organization or organizational unit. If you are using an -.indexed database with QUIPU, you may need to create EDB -.files from your index files (using the synctree or qb2edb -.tools). -. - -+If you do not have a file named EDB.root in the same -.directory that contains your organizational or organizational -.unit entry, create it now by hand. Its contents should look -.something like this: -. -.{{EX: MASTER}} -.{{EX: 000001}} -.{{EX: }} -.{{EX: o=OpenLDAP}} -.{{EX: objectClass= top & organization & domainRelatedObject &\}} -.{{EX: quipuObject & quipuNonLeafObject}} -.{{EX: l= Redwood City, California}} -.{{EX: st= California}} -.{{EX: o=OpenLDAP Project & OpenLDAP Foundation & OpenLDAP}} -.{{EX: description=The OpenLDAP Project}} -.{{EX: associatedDomain= openldap.org}} -.{{EX: masterDSA= c=US@cn=Woolly Monkey}} -.{{EX: }} - -+ (Optional) Create a global add file and/or local .add files to -.take care of adding any attribute values that do not appear in -.the EDB files. For example, if all entries in a particular EDB -.are person entries and you want to add the appropriate -.objectClass attribute value for them, create a file called .add -.in the same directory as the person EDB that contains the -.single line: -. -.{{EX: objectClass: person }} -. - -+ Run the edb2ldif program to do the actual conversion. -.Make sure you are in the directory that contains the root of -.the EDB hierarchy (the one where the EDB.root file resides). -.Include a -b flag with a base DN one level above your -.organizational entry, and include -i flags to ignore any -.attributes that are not useful to slapd. E.g., the command: -. -.{{EX: edb2ldif -v -r -b "c=US" -i iattr -i acl -i xacl -i sacl}} -.{{EX: -i lacl -i masterDSA -i slaveDSA > ldif}} -. -.will convert the entire EDB hierarchy to LDIF format and -.write the result to a file named ldif. Some attributes that are -.not useful when running slapd are ignored. The EDB -.hierarchy is assumed to reside logically below the base DN -."c=US". -. - -+ Follow the steps outlined in section 8.2 above to produce -.an LDBM database from your new LDIF file. - - - -H2: The ldbmtest program - -Occasionally you may find it useful to look at the LDBM -database and index files directly (i.e., without going through -slapd). The {{EX: ldbmtest}} program is provided for this purpose. It -gives you raw access to the database itself. {{EX: ldbmtest}} should -be run line this: - -E: ldbmtest [-d ] [-f ] - -The default configuration file in the {{EX: ETCDIR}} is used if you -don't supply one. By default, ldbmtest operates on the last -database listed in the config file. You can specify an -alternate database, or see the current database with the -following commands. - -E: b specify an alternate backend database -E: B print out the current backend database - -The {{EX: b}} command will prompt you for the suffix associated with -the database you want. The database you select can be -viewed and modified using a set of two-letter commands. -The first letter selects the command function to perform. -Possible commands and their meanings are as follows. - -E: l lookup (do not follow indirection) -E: L lookup (follow indirection) -E: t traverse and print keys and data -E: T traverse and print keys only -E: x delete an index item -E: e edit an index item -E: a add an index item -E: c create an index file -E: i insert an entry into an index item - -The second letter indicates which index the command -applies to. The possible index selections are as follows. - -E: c id2children index -E: d dn2id index -E: e id2entry index -E: f arbitrary file name -E: i attribute index - -Each command may require additional arguments which -ldbmtest will prompt you for. - -To exit {{EX: ldbmtest}}, type {{EX: control-D}} or {{EX: control-C}}. - -Note that this is a very raw interface originally developed -when testing the database format. It is provided and -minimally documented here for interested parties, but it is not -meant to be used by the inexperienced. See the next section -for a brief description of the LDBM database format. - - - -H2: The LDBM database format - -In normal operation, it is not necessary for you to know much -about the LDBM database format. If you are going to use the -ldbmtest program to look at or alter the database, or if you -want a deeper understanding of how indexes are maintained, -some knowledge of how it works could be useful. This -section gives an overview of the database format and how -slapd makes use of it. - - - -H3: Overview - -The LDBM database works by assigning a compact -four-byte unique identifier to each entry in the database. It -uses this identifier to refer to entries in indexes. The -database consists of one main index file, called id2entry, -which maps from an entry's unique identifier (EID) to a text -representation of the entry itself. Other index files are -maintained, for each indexed attribute for example, that map -values people are likely to search on to lists of EIDs. - -Using this simple scheme, many LDAP queries can be -answered efficiently. For example, to answer a search for -entries with a surname of "Jensen", slapd would first consult -the surname attribute index, look up the value "Jensen" and -retrieve the corresponding list of EIDs. Next, slapd would -look up each EID in the id2entry index, retrieve the -corresponding entry, convert it from text to LDAP format, and -return it to the client. - -The following sections give a very brief overview of each -type of index and what it contains. For more detailed -information see the paper "An X.500 and LDAP Database: -Design and Implementation," available in postscript format -from - -{{CMD[jump="ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps"]ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps}} - - - -H3: Attribute index format - -The LDBM backend will maintain one index file for each -attribute it is asked to index. Several sets of keys must -coexist in this file (e.g., keys for equality and approximate -equality), so the keys are prefixed with a character to ensure -uniqueness. The prefixes are given in the table below - -E: = equality keys -E: ~ approximate equality keys -E: * substring equality keys -E: \ continuation keys - -Key values are also normalized (e.g., converted to upper -case for case ignore attributes). So, for example, to look up -the surname equality value in the example above using the -ldbmtest program, you would look up the value "{{EX: =JENSEN}}". - -Substring indexes are maintained by generating all possible -N-character substrings for a value (N is 3 by default). These -substrings are then stored in the attribute index, prefixed by -"*". Additional anchors of "^" and "$" are added at the -beginning and end of words. So, for example the surname of -Jensen would cause the following keys to be entered in the -index: {{EX: ^JE, JEN, ENS, NSE, SEN, EN$}}. - -Approximate values are handled in a similar way, with -phonetic codes being generated for each word in a value -and then stored in the index, prefixed by "~". - -Large blocks in the index are split into smaller ones. The -smaller blocks are accessed through a level of indirection -provided by the original block. They are stored in the index -using the continuation key prefix of "\". - - - -H3: Other indexes - -In addition to the {{EX: id2entry}} and attribute indexes, LDBM -maintains a number of other indexes, including the {{EX: dn2id}} -index and the {{EX: id2children}} index. These indexes provide the -mapping between a DN and the corresponding EID, and the -mapping between an EID and the EIDs of the corresponding -entry's children, respectively. - -The {{EX: dn2id}} index stores normalized DNs as keys. The data -stored is the corresponding EID. - -The {{EX: id2children}} index stores EIDs as keys. The data stored -is a list of EIDs, just as for the attribute indexes. - - -PB: +> dn: cn=Barbara J Jensen,dc=example,dc=com +> cn: Barbara J Jensen +Multiple attribute values are specified on separate lines. e.g., +> cn: Barbara J Jensen +> cn: Babs Jensen + +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= + +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.