Creating the ds.conf file

This section contains information that is necessary for creating the ds.conf configuration file.

Locating ds.conf

All LDAP server runtime configuration is accomplished through the configuration file ds.conf, installed in the /usr/lpp/ldap/etc directory. If this is your first time installing the LDAP server, create a new copy of ds.conf with:

cp /usr/lpp/ldap/etc/ds.conf /etc/ldap/ds.conf

and edit /etc/ldap/ds.conf.

The default LDAP server configuration file is /etc/ldap/ds.conf. A different configuration file can be specified using the -f command-line parameter when starting the LDAP server, ds2ldif, and ldif2ds utilities.

The initial configuration contains default versions of some configuration settings. It does not contain a database suffix.

Configuration file format

The ds.conf file consists of the following sections:

Global section: Contains configuration options that apply to the LDAP server as a whole (including all backends).
SDBM backend-specific section: Contains configuration options that apply to the SDBM backend.
TDBM backend-specific section: Contains configuration options that apply to the TDBM backend. It is possible to have one or more of these sections depending on how many TDBM backends your installation uses.
GDBM (DB2®-based) backend-specific section: Contains configuration options that apply to the DB2-based GDBM change log backend. The configuration of either type of GDBM change log backend is mutually exclusive. The LDAP server ends when a file-based GDBM backend and a DB2-based GDBM backend are both configured in the same configuration file.
LDBM backend-specific section: Contains configuration options that apply to the LDBM backend. It is possible to have one or more of these sections depending on how many LDBM backends your installation uses.
GDBM (file-based) backend-specific section: Contains configuration options that apply to the file-based GDBM change log backend. The configuration of either type of GDBM change log backend is mutually exclusive. The LDAP server ends when a file-based GDBM backend and a DB2-based GDBM backend are both configured in the same configuration file.
CDBM backend-specific section: Contains configuration options that apply to the file-based CDBM backend.
EXOP backend-specific section (deprecated): Contains only the database statement necessary for the EXOP backend.

Figure 1 shows the general format of ds.conf.

# Global options - these options apply to every database
<global configuration options>
 
# SDBM database definition and configuration options
database SDBM GLDBSD31/GLDBSD64
<configuration options specific to SDBM backend>
 
# TDBM database definition and configuration options
database TDBM GLDBTD31/GLDBTD64
<configuration options specific to TDBM backend> 
 
# DB2-based GDBM database definition and configuration options
database GDBM GLDBGD31/GLDBGD64
<configuration options specific to DB2-based GDBM backend

# LDBM database definition and configuration options
database LDBM GLDBLD31/GLDBLD64
<configuration options specific to LDBM backend>

# File-based GDBM database definition and configuration options
database GDBM GLDBGD31/GLDBGD64
<configuration options specific to file-based GDBM backend>

# CDBM database definition and configuration options
database CDBM GLDBCD31/GLDBCD64
<configuration options specific to CDBM backend>

# EXOP database definition and configuration options (deprecated)
database EXOP GLDXPD31/GLDXPD64

Figure 1. General format of ds.conf

Noted below are some rules for setting up ds.conf:

The configuration file contains a global section containing options that apply to the entire LDAP server, followed by one or more database backend sections that contain options that apply to a specific backend. Each backend section begins with a database option and continues to the next database option. The global section starts at the beginning of the configuration file and ends at the first database option. The sizelimit and timelimit options can be either global or specific to a backend: they are global if they appear in the global section and are specific to a backend if they appear in a backend section. See the sizelimit configuration file option on page sizeLimit num-limit and the timeLimit configuration file option on page timeLimit num-seconds for more information.
The configuration file must be in code page IBM-1047.
The maximum length of a line in the configuration file is 1024 characters.
Each configuration line consists of an option and a value separated by one or more blanks. Begin each configuration option in column one. The option is not case-sensitive. The value might not be case-sensitive depending upon the option. If an argument contains one or more blank spaces, the value is enclosed in double quotation marks (for example, "value one"). If a value contains a double quotation mark or a backslash character (\), the double quotation mark or backslash character is preceded by a backslash character (\).
A line that begins with a space or tab character in column one is considered a continuation of the previous line. Everything after the space or tab character is appended to the previous line. The maximum length of the initial line plus all continuation lines is 1024 characters.
A line that begins with a number sign (#) in column one is a comment line. Comment lines can be continued and are ignored.
A number sign (#) can be used to add a comment to the end of a configuration line. The number sign (#) must be separated from the option value by at least one blank. Anything following the number sign (#) is ignored, including any continuation lines. A number sign (#) is not treated as the start of a comment if it occurs within a quoted value.
Blank lines can be used to separate configuration lines.
Options that expect a value of on or off also accepts yes, y, no, and n. The option value is not case-sensitive.
For single-valued options that appear more than once, the last appearance in the ds.conf file is used.

Specifying a value for filename

For configuration file options that contain the filename value, the value can be specified in one of the following ways:

/pathname/filename: Specifies the full path name of a file in the z/OS® UNIX System Services file system.
filename: Specifies a file name in the z/OS UNIX System Services file system that is relative to the current working directory of the LDAP server. The LDAP server sets the current working directory to the value of the HOME environment variable or to /etc/ldap if the HOME environment variable is not defined. This format is not suggested.
//’dataset.name’: Specifies the fully-qualified name of a file stored in a sequential data set.
//’dataset.name(member)’: Specifies the fully-qualified name of a file stored in a partitioned data set.
//DD:DDNAME: Specifies the DDNAME for a JCL DD statement that defines the file. The file might be in a z/OS UNIX System Services file system, a sequential data set, or a member of a partitioned data set.

Specifying a value for a distinguished name

The value for the following configuration options is a distinguished name (DN): adminDN, krbLDAPAdmin, masterServerDN, peerServerDN, nativeAuthSubtree, and suffix. Also, the wlmExcept configuration option optionally accepts a distinguished name (DN). Special characters (as identified in RFC 2253: Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names) used in the DN must be properly escaped using two back slashes (\\). Note that the double back slashes are only needed in the configuration file; in all other usages, the special characters are typically prefixed by a single backslash. See Accessing RACF information for exceptions to this when using SDBM. See IETF RFC 2253 Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names for valid DN formats. Also, see Distinguished name syntax for more information about distinguished name syntax.

For example, to use a RACF® user ID #1admin as the LDAP root administrator defined in the configuration file, the adminDN configuration option might look like:

adminDN "racfid=\\#1admin,profiletype=user,cn=myRacf"

With LDAP V3 support, UTF-8 characters can be used for textual attributes stored in the directory. It is preferred to allow any UTF-8 character to appear in distinguished names, and in particular, the adminDN distinguished name. Because the LDAP configuration files are defined to hold information in the IBM-1047 character set, a solution is required for the configuration files that allows you to use distinguished names containing UTF-8 characters but using only the IBM-1047 character set. To solve this problem, an escape mechanism has been introduced for purposes of entering a DN. This escape mechanism allows the entry of UTF-8 characters while keeping the input string value to within the IBM-1047 character set. The escape mechanism employed requires that you express UTF-8 characters that are not within the X'00' - X'7F' range (7-bit ASCII that is the single-byte form of UTF-8 characters) in the form of a set of four character representations. This representation has the form "&nmm" where 0<n<3 and 0<m<7. You might recognize nmm as being an octal value for a byte of information. Therefore, if you want to create the following distinguished name:

cn=Peter <U umlaut>nger, o=Widgets, c=DE

specify the DN as:

cn=Peter &nmm&nmmnger, o=Widgets, c=DE

Because the <U umlaut> is not within the 7-bit ASCII range, the value must be escaped to the octal representation of the UTF-8 multi-byte character. For <U umlaut>, the Unicode code point is X'00DC'. Converted to UTF-8, this character is a multi-byte sequence: X'C39C'. (See UTF-8 support for conversion information.) Converted to the escaped form for input into the DN field, this character is represented as "&303&234" because X'C3' is octal 303 and X'9C' is octal 234. Therefore, the DN above is entered as:

cn=Peter &303&234nger, o=Widgets, c=DE

If there is a case where you must enter a DN that contains the string "&nmm" where 0<n<3 and 0<m<7, then you must escape the ampersand by using its octal representation which is "046".

There are several restrictions concerning the attributes used in a DN:

The default matching rule for an attribute used in a DN that is not contained in the LDAP server schema is caseIgnoreMatch. This results in this part of the DN being normalized by using uppercase in the attribute value. If the attribute is later defined in the schema and the matching rule is not caseIgnoreMatch, that part of the DN might now be normalized differently. Therefore, the normalized version of the DN used in an operation might not match the normalized version of the DN in the configuration file, resulting in the failure of the operation.

In particular, if an attribute used in a suffix is not in the LDAP server schema and is later added to the schema with a different matching rule, then restart the LDAP server after the schema definition is added. Otherwise, operations using that suffix can fail.
Do not use an attribute with Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) in a DN in the configuration file, especially in a suffix. Integer attribute values in a normalized DN have a special format that might cause problems within the LDAP server.

Configuration file checklist

The following table is provided to assist you in determining which configuration file options you must use in your ds.conf file. Depending on the section in the configuration file (Global, SDBM, TDBM, GDBM, LDBM, CDBM, or EXOP), certain topics (SSL, schema, basic replication, and so on) have options that are required or optional.

Table 1. Configuration file options checklist
Section/topic	Options
Global	adminDN is required. adminPW, allowAnonymousBinds, altServer, armName, audit, commThreads, db2StartUpRetryInterval, db2StartUpRetryLimit, db2Terminate, digestRealm, dnCacheSize, idleConnectionTimeout, include, listen, maxConnections, operationsMonitor, operationsMonitorSize, pcIdleConnectionTimeout, pcThreads, plugin, pwSearchOutput, referral, schemaPath, schemaReplaceByValue, securityLabel, sendV3stringsoverV2as, serverCompatLevel, serverEtherAddr, sizeLimit, srvStartUpError, tcpTerminate, timeLimit, validateincomingV2strings, and wlmExcept are optional.
SSL/TLS	sslKeyRingFile is required if a listen option is initialized for secure socket communications or a listen option is initialized for non-secure socket communications that is intended to support switching to secure socket communications when the connection is established. sslAuth, sslCertificate, sslCipherSpecs, sslKeyRingFilePW, sslKeyRingPWStashFile, and sslMapCertificate are optional.
Sysplex	serverSysplexGroup is required.
Kerberos	supportKrb5 is required. krbKeytab, krbLDAPAdmin, and serverKrbPrinc are optional.
Activity logging	logfile is required. logFileFilter, logFileRolloverDirectory, logFileRolloverSize, and logFileRolloverTOD are optional.
SDBM backend	database and suffix are required. enableResources, include, readOnly, sizeLimit and timeLimit are optional.
Kerberos	krbIdentityMap is required.
TDBM backend	database, dbuserid, and suffix are required. aclSourceCacheSize, attrOverflowCount, attrOverflowSize, changeLoggingParticipant, dnToEidCacheSize, dsnaoini, entryCacheSize, entryOwnerCacheSize, extendedGroupSearching, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readonly, serverName, sizeLimit, and timeLimit are optional.
Attribute encryption or hashing	pwCryptCompat, pwEncryption, and secretEncryption are optional.
Basic replication	Either peerServerDN or both masterServer and masterServerDN are required. peerServerPW and masterServerPW are optional.
Multi-server	multiserver is required.
Kerberos	krbIdentityMap is required.
Native authentication	useNativeAuth and nativeAuthSubtree are required. nativeUpdateAllowed is optional.
GDBM backend (DB2-based)	database and dbuserid are required. aclSourceCacheSize, attrOverflowSize, changeLogging, changeLoggingParticipant, changeLogMaxAge, changeLogMaxEntries, dnToEidCacheSize, dsnaoini, entryCacheSize, entryOwnerCacheSize, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readonly, serverName, sizeLimit, and timeLimit are optional.
Multi-server	multiserver is required.
LDBM backend	database and suffix are required. attrOverflowCount, changeLoggingParticipant, commitCheckpointEntries, commitCheckpointTOD, databaseDirectory, extendedGroupSearching, fileTerminate, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readOnly, sizeLimit, and timeLimit are optional.
Attribute encryption or hashing	pwCryptCompat, pwEncryption, and secretEncryption are optional.
Basic replication	Either peerServerDN or both masterServer and masterServerDN are required. peerServerPW and masterServerPW are optional.
Multi-server	multiserver is required.
Kerberos	krbIdentityMap is required.
Native authentication	useNativeAuth and nativeAuthSubtree are required. nativeUpdateAllowed is optional.
GDBM backend (file-based)	database is required. changeLogging, changeLoggingParticipant, changeLogMaxAge, changeLogMaxEntries, commitCheckpointEntries, commitCheckpointTOD, databaseDirectory, fileTerminate, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readOnly, sizeLimit, and timeLimit are optional.
Multi-server	multiserver is required.
CDBM backend	database is required. attrOverflowCount, changeLoggingParticipant, commitCheckpointEntries, commitCheckpointTOD, databaseDirectory, extendedGroupSearching, fileTerminate, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readOnly, sizeLimit, and timeLimit are optional.
Attribute encryption or hashing	pwCryptCompat, pwEncryption, and secretEncryption are optional.
Advanced replication	useAdvancedReplication is required.
Multi-server	multiserver is required.
Kerberos	krbIdentityMap is required.
Native authentication	useNativeAuth and nativeAuthSubtree are required. nativeUpdateAllowed is optional.
EXOP backend (deprecated)	database is required. include is optional.

Note: The adminDN configuration option is required and specifies the LDAP root administrator in the configuration file. The password for this LDAP root administrator can be specified in a directory entry or in the adminPW configuration option. See Establishing the root administrator DN and basic replication replica server DN and passwords for more information. Note the use of the adminPW configuration option is discouraged. Instead, an existing entry in the directory is designated as the adminDN.

If the distinguished name specified for the adminDN configuration option does not exist within a configured backend suffix and the password is specified in the adminPW configuration option, password policy is not supported for the LDAP root administrator defined in the configuration file.