Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.
+