diff options
Diffstat (limited to 'doc/guide/admin/dbtools.sdf')
| -rw-r--r-- | doc/guide/admin/dbtools.sdf | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/doc/guide/admin/dbtools.sdf b/doc/guide/admin/dbtools.sdf new file mode 100644 index 0000000..df29ead --- /dev/null +++ b/doc/guide/admin/dbtools.sdf @@ -0,0 +1,382 @@ +# $OpenLDAP$ +# Copyright 1999-2022 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 {{TERM: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}}(8). 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 utilities. + + +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 <dn> + +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" + +You should be sure to specify a directory where the index files +should be created: + +> directory <directory> + +For example: + +> 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 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 <dn> +> rootpw <passwd> + +For example: + +> 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. + +Finally, you should make sure that the database definition contains +the index definitions you want: + +> 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: + +> 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 +> +> # 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: + +> ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret + +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 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). Also, +the input file must be completely valid, as these tools do fewer +consistency checks than the on-line method. + +Note: this Guide is not meant to provide exhaustive documentation +on the software. The tool descriptions here only list a few of the +available options for each command. Read the associated manpages for +complete documentation on all of the available options. + +There are several important configuration options you will want to be +sure and set in the config file database definition first: + +> suffix <dn> + +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" + +You should be sure to specify a directory where the index files +should be created: + +> directory <directory> + +For example: + +> directory /usr/local/var/openldap-data + +Finally, you need to specify which indices you want to build. This +is done by one or more index options. + +> index {<attrlist> | default} [pres,eq,approx,sub,none] + +For example: + +> 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 + +Once you've configured things to your liking, you create the primary +database and associated indices by running the {{slapadd}}(8) +program: + +> slapadd -l <inputfile> -f <slapdconfigfile> +> [-d <debuglevel>] [-n <integer>|-b <suffix>] + +The arguments have the following meanings: + +> -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 slapd configuration file that tells where to create +the indices, what indices to create, etc. + +> -F <slapdconfdirectory> + +Specifies a config directory. If both {{EX:-f}} and {{EX:-F}} are specified, +the config file will be read and converted to config directory format and +written to the specified directory. If neither option is specified, an attempt +to read the default config directory will be made before trying to use the +default config file. If a valid config directory exists then the default +config file is ignored. If dryrun mode is also specified, no conversion will occur. + +> -d <debuglevel> + +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}}. + +> -n <databasenumber> + +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 <suffix> + +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. {{slapindex}} is invoked like this + +> slapindex -f <slapdconfigfile> +> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] [attr...] + +Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options +are the same as for the {{slapadd}}(1) program. If no specific +attributes are listed, {{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: + +> slapcat -l <filename> -f <slapdconfigfile> +> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] + +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 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] <attrdesc> + +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. + +> ldif description << EOF +> leading space +> # leading hash mark +> EOF + +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 {{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}}. + +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 + +is equivalent to: + +> 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:<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}}. + +> jpegPhoto:< 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. + |