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
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 at sizeLimit num-limit and the timeLimit configuration file option at 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) 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 RFC 2253 for valid DN formats. Also, see Distinguished name syntax for more information about distinguished name syntax.
#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"
cn=Peter <U umlaut>nger, o=Widgets, c=DE
cn=Peter &nmm&nmmnger, o=Widgets, c=DE
<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".
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.
Section/topic | Options |
---|---|
Global | adminDN is required. adminPW, allowAnonymousBinds, altServer, armName, audit, blockedConnectionTimeout, commThreads, db2StartUpRetryInterval, db2StartUpRetryLimit, db2Terminate, digestRealm, dnCacheSize, healthcheck, idleConnectionTimeout, include, listen, maxConnections, operationsMonitor, operationsMonitorSize, pcIdleConnectionTimeout, pcThreads, plugin, pwSearchOutput, referral, schemaPath, schemaReplaceByValue, securityLabel, sendV3stringsoverV2as, serverCompatLevel, serverEtherAddr, sizeLimit, srvStartUpError, tcpTerminate, timeLimit, unbufferedEntryLimit, 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, sslFipsState, 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, logFileMicroseconds, logFileMsgs, logFileOps, logFileRecordType, logFileRolloverDirectory, logFileRolloverSize, logFileRolloverTOD, and logFileVersion 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, fetchSize, 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. |
Health check | If db2CheckHealth is db2ExtentLimit, db2RRIAppendInsertPct, db2RRIDeletesAbs, db2RRIDeletesPct, db2RRIInsertsAbs, db2RRIInsertsPct, db2RRILeafLimit, db2RRIMassDelLimit, db2RRINumLevelsLimit, db2RRIPseudoDeletePct, db2RRTDataSpaceRat, db2RRTDeletesAbs, db2RRTDeletesPct, db2RRTDisorgLOBPct, db2RRTIndRefLimit, db2RRTInsertsAbs, db2RRTInsertsPct, db2RRTMassDelLimit, db2RRTUnclustInsPct, db2SRIInsDelAbs, db2SRIInsDelPct, db2SRIMassDelLimit, db2SRTInsDelUpdAbs, db2SRTInsDelUpdPct, and db2SRTMassDelLimit. |
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, fetchSize, filterCacheBypassLimit, filterCacheSize, include, persistentSearch, readonly, serverName, sizeLimit, and timeLimit are optional. |
Health check | If db2CheckHealth is db2ExtentLimit, db2RRIAppendInsertPct, db2RRIDeletesAbs, db2RRIDeletesPct, db2RRIInsertsAbs, db2RRIInsertsPct, db2RRILeafLimit, db2RRIMassDelLimit, db2RRINumLevelsLimit, db2RRIPseudoDeletePct, db2RRTDataSpaceRat, db2RRTDeletesAbs, db2RRTDeletesPct, db2RRTDisorgLOBPct, db2RRTIndRefLimit, db2RRTInsertsAbs, db2RRTInsertsPct, db2RRTMassDelLimit, db2RRTUnclustInsPct, db2SRIInsDelAbs, db2SRIInsDelPct, db2SRIMassDelLimit, db2SRTInsDelUpdAbs, db2SRTInsDelUpdPct, and db2SRTMassDelLimit. |
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. |
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.