|Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Reference|
This chapter provides an overview of the files stored under the instance directory, ServerRoot/slapd-serverID. Having an overview of the files and configuration information stored in each instance of Directory Server helps you understand the file changes or absence of file changes that occur in the course of directory activity. It also helps you to detect errors and intrusion, by indicating what kind of changes to expect, and as a result, what changes are considered abnormal.
Overview of Directory Server Files
This chapter is divided into the following sections:
Each section describes the file type and contents.
Each Directory Server instance contains the following three directories for storing backup related files:
- bak - the default directory in which database backups (created with the db2bak script) are placed. The bak directory contains one directory for each database backup, the name of which corresponds to the time and date of the backup, for example 2004_12_13_17_45_24. This directory holds the backup copy of the database. To specify an alternative location for the database backups, use the db2bak command as described in the Directory Server Man Page Reference.
- confbak - the default directory in which the Administration Server configuration is stored, (and from which the configuration is read) when the saveconfig and restoreconfig scripts are used. For information about these scripts, refer to the Directory Server Man Page Reference.
- conf_bk - contains a backup copy of the dse.ldif configuration file from the time of installation. This copy can be used for comparison with the current configuration file, should problems arise.
Each Directory Server instance contains the following directory for storing configuration files:
- config - contains the configuration files as explained in Server Configuration Overview.
The dse.ldif file is a configuration file for each directory instance, whereas the Administration Server configuration (everything under o=NetscapeRoot) is only in the configuration directory. The configuration directory is usually the first directory that was installed, or may be a completely separate instance.
For small deployments, it is possible to install configuration, user and other directories on the same directory instance. For larger deployments, consider placing the configuration directory in its own instance. Refer to the Administration Server Administration Guide for information on the appropriate location of configuration, user and group data.
Each Directory Server instance contains the db directory for storing all the database files. The following list shows the sample contents of the db directory at installation.
DBVERSION __db.002 __db.005
NetscapeRoot/ __db.003 log.0000017
__db.001 __db.004 userRoot/
- db.00x files - used internally by the database. These files should not be moved, deleted, or modified in any way.
- log.xxxxxxxxxx files - store the transaction logs per database.
- DBVERSION - stores the version of the database.
- NetscapeRoot - this directory stores the o=NetscapeRoot database created by default during a typical installation. This branch of the directory stores admin server configuration information. The same configuration directory can be used to store the admin server configuration information for all directory instances. Refer to the Administration Server Administration Guide for information on the appropriate location of configuration, user and group data.
- userRoot - this directory stores the user-defined suffix (user-defined databases) created during a typical installation, for example dc=example,dc=com.
The following list shows the sample contents of the NetscapeRoot directory:
To ensure that database filenames are unique across suffixes, the files are prefixed with the suffix name. So, for the NetscapeRoot suffix in the above example, all the filenames in the directory start with NetscapeRoot_.
The NetscapeRoot and userRoot subdirectories contain a file of the format suffix_ index_name.db3 for every index currently defined in the database (where index_name is the name of the attribute being indexed). In addition to these suffix_index_name.db3 files, the subdirectories contain a file named suffix_id2entry.db3. This file contains the actual directory database entries. All other database files can be recreated from this one, if necessary.
Each Directory Server instance contains the ldif directory for storing ldif related files. The following list shows the default contents of the ldif directory.
The following list describes the contents of each of the LDIF files:
- European.ldif - contains European character samples.
- Example.ldif - a sample ldif file.
- Example-roles.ldif - a sample ldif file similar to Example.ldif except that it uses roles and class of service instead of groups for setting access control and resource limits for Directory Administrators
- Example-Plugin.ldif - a sample ldif file to be used with the examples provided in the Directory Server Plug-in Developer's Reference.
- identityMapping_Examples.ldif - a sample identity mapping configuration file. For more information on identity mapping, refer to the Directory Server Administration Guide.
Each Directory Server instance contains a locks directory for storing lock related files. The following list shows the sample contents of the locks directory.
The lock mechanisms stored under the subdirectories exports, imports, and server prevent simultaneous operations from conflicting with each other. The lock mechanisms allow one server instance to run at a time, with possible multiple export jobs. They also permit only one directoryserver ldif2db operation at a time. This means that no export and slapd server operations can be run during an import.
This restriction does not apply to directoryserver ldif2db-task, since you can run multiple ldif2db-task operations at any time.
Directory Server provides you with logs to help you monitor directory activity. Monitoring allows you to detect and remedy failures and, when done proactively, to anticipate and resolve potential problems before they result in failure or poor performance. To monitor your directory effectively, you need to understand the structure and content of the logs.
This section covers the following topics related to logs:
For information on the error codes returned in log files, refer to Appendix A, "Error Codes."
Log File Layout
Each Directory Server instance contains a logs directory for storing log related files. The following list shows a sample of the logs directory contents.
access audit.rotationinfo pid
access.rotationinfo errors slapd.stats
- The content of the access, audit, and errors log files is dependent on the log configuration.
- The slapd.stats file is a memory-mapped file that cannot be read in an editor. It contains data collected by the Directory Server SNMP data collection component. This data is read by the SNMP subagent in response to SNMP attribute queries and is communicated to the SNMP master agent responsible for handling Directory Server SNMP requests.
- The pid is the slapd process identifier.
Access Log Content
The Directory Server access log contains detailed information about client connections to the directory. A connection is a sequence of requests from the same client with the following structure:
The access log files are located in the directory ServerRoot/slapd-serverID/logs. Each line of a log file begins with a timestamp [20/Aug/2002:11:39:51 -0700], where -0700 indicates the time difference in relation to GMT. The format of the timestamp may vary depending on the platform you are using. Apart from the connection, closed, and abandon records that appear individually, all records appear in pairs, consisting of a request for service record followed by a result record. These two records frequently appear on adjacent lines but this is not always the case.
This section presents the different levels of access logging available with Directory Server, then describes the default access logging content and ends with a description of the additional access logging level content. This section is divided into the following parts:
Access Logging Levels
Different levels of access logging exist. By changing the value of the nsslapd-accesslog-level configuration attribute, you can select the exact type of logging you require. The default level of logging is level 256 which logs access to an entry but you can choose from the following logging levels, combining more than one level to suit your needs:
0=No access logging
4=Logging for internal access operations
256=Logging for access to an entry
512=Logging for access to an entry and referrals
131072=Precise timing of operation duration. This gives microsecond resolution for the Elapsed Time item in the access log.
For example, if you want to log internal access operations, entry access, and referrals, you would set a value of 516 (512+4) in the nsslapd-accesslog-level configuration attribute. For further information on other access log configuration attributes, refer to Chapter 4, "Core Server Configuration Attributes."
Default Access Logging Content
This section describes the access log content in detail, based on the default access logging level extract in Code Example 3-1.
Code Example 3-1 Access Log Extract with Default Access Logging Level (Level 256)
[22/Oct/2002:12:05:04 +0200] conn=25 op=-1 msgId=-1 - fd=32 slot=32 LDAP connection from 127.0.0.1 to 127.0.0.1
[22/Oct/2002:12:05:04 +0200] conn=25 op=0 msgId=1 - BIND dn="cn=Directory Manager" method=128 version=3
[22/Oct/2002:12:05:04 +0200] conn=25 op=0 msgId=1 - RESULT err=0 tag=97 nentries=0 etime=0 dn="cn=directory manager"
[22/Oct/2002:12:07:19 +0200] conn=25 op=1 msgId=2 - ADD dn="cn=Simon Campbell,ou=People,dc=Example,dc=COM"
[22/Oct/2002:12:07:20 +0200] conn=25 op=1 msgId=2 - RESULT err=0 tag=105 nentries=0 etime=1
[22/Oct/2002:12:07:26 +0200] conn=25 op=2 msgId=3 - UNBIND
[22/Oct/2002:12:07:26 +0200] conn=25 op=2 msgId=-1 - closing (3 ops still in progress) - U1
[22/Oct/2002:12:07:27 +0200] conn=25 op=-1 msgId=-1 - closed.
[22/Oct/2002:12:09:43 +0200] conn=26 op=-1 msgId=-1 - fd=32 slot=32 HTTP connection from 18.104.22.168 to 22.214.171.124
[22/Oct/2002:12:09:45 +0200] conn=26 op=0 msgId=0 - DSML Batch Request requestID=""
[22/Oct/2002:12:09:45 +0200] conn=26 op=2 msgId=1 - DSML Modify requestID="" (parent msgId="0")
[22/Oct/2002:12:09:45 +0200] conn=26 op=2 msgId=1 - MOD dn="cn=Simon Campbell,ou=People,dc=Example,dc=COM"
[22/Oct/2002:12:09:45 +0200] conn=26 op=2 msgId=1 - RESULT err=0 tag=103 nentries=0 etime=0
[22/Oct/2002:12:09:45 +0200] conn=26 op=0 msgId=-1 - protocol=HTTP host="Foo" remlog="-" uname="-" date="[Tue, 22 Oct 2002 10:09:46 GMT]" request="POST /dsml HTTP/1.1" status="200 OK" length=565
[22/Oct/2002:12:09:45 +0200] conn=26 op=0 msgId=-1 - closing (3 ops still in progress) - (HTTP closure.)
[22/Oct/2002:12:09:46 +0200] conn=26 op=-1 msgId=-1 - closed.
[22/Oct/2002:12:11:01 +0200] conn=27 op=-1 msgId=-1 - fd=32 slot=32 LDAP connection from 127.0.0.1 to 127.0.0.1
[22/Oct/2002:12:11:01 +0200] conn=27 op=0 msgId=1 - BIND dn="cn=Directory Manager" method=128 version=3
[22/Oct/2002:12:11:01 +0200] conn=27 op=0 msgId=1 - RESULT err=0 tag=97 nentries=0 etime=0 dn="cn=directory manager"
[22/Oct/2002:12:11:01 +0200] conn=27 op=1 msgId=2 - SRCH base="dc=Example,dc=COM" scope=2 filter="(uid=scampbell)" attrs=ALL
[22/Oct/2002:12:11:01 +0200] conn=27 op=1 msgId=2 - RESULT err=0 tag=101 nentries=1 etime=0
[22/Oct/2002:12:11:01 +0200] conn=27 op=2 msgId=3 - UNBIND
[22/Oct/2002:12:11:01 +0200] conn=27 op=2 msgId=-1 - closing (3 ops still in progress) - U1
[22/Oct/2002:12:11:02 +0200] conn=27 op=-1 msgId=-1 - closed.
Every external request is listed with an incremental connection number (conn=25, conn=26, and conn=27 in the preceding example), starting at conn=0 immediately after server startup. In this example, conn=25 contains an LDAP add operation, conn=26 contains a DSML add operation and conn=27 contains an LDAP search operation.
Internal LDAP requests are not recorded in the access log by default. To activate the logging of internal access operations, specify an access logging level of 4 in the nsslapd-accesslog-level configuration attribute.
Every connection from an external LDAP client to Directory Server requires a file descriptor, or socket descriptor, from the operating system (fd=32 in the preceding example). fd=32 indicates that file descriptor number 32 was used from the total pool of available file descriptors.
The slot number (slot=32 in the preceding example), has the same meaning as file descriptor. It is a legacy section of the access log and can be ignored.
In processing an external request, Directory Server performs the required series of operations. For a specific connection, all operation request and operation result pairs are given incremental operation numbers beginning with op=0 to identify the distinct operations being performed. In Code Example 3-1, op=0 is given for the bind operation request and result pair, then op=1 for the LDAP search request and result pair, and so on. Should you see op=-1 in the access log, it generally means that the LDAP request for this connection was not issued by an external LDAP client, but instead initiated internally.
The method number, in this case method=128, indicates which LDAPv3 bind method was used by the client. There are three possible bind method values:
0 = no authentication
128 = simple bind with user password
sasl= SASL bind using external authentication mechanism
The version number, in this case version=3, indicates the LDAP version number (either LDAPv2 or LDAPv3) that the LDAP client used to communicate with the LDAP server.
The error number, in this case err=0, provides the LDAP result code returned from the LDAP operation performed. The LDAP error number 0 means that the operation was successful. For a more comprehensive list of LDAP result codes refer to LDAP Result Codes.
Directory Server exposes Basic Encoding Rules tag numbers in log files for historical reasons. The tags are used internally when decoding messages, and are not intended for use outside Directory Server.
The tag number, in this case tag=97, indicates the type of result returned, which is almost always a reflection of the type of operation performed. Commonly used tags that identify standard operations include:
tag=97 for a result from a client bind operation
tag=100 indicates the actual entry for which you were searching
tag=101 for a result from a search operation
tag=103 for a result from a modify operation
tag=105 for a result from an add operation
tag=107 for a result from a delete operation
tag=109 for a result from a moddn operation
tag=111 for a result from a compare operation
tag=115 indicates a search reference when the entry you perform your search on holds a referral to the entry you require. Search references are expressed in terms of a referral.
tag=120 for a result from an extended operation
Number of Entries
The number of entries, in this case nentries=0, indicates the number of entries that were found matching the LDAP client's request.
Elapsed time, in this case etime=1000, indicates the amount of time (in seconds) that it took Directory Server to perform the LDAP operation. An etime value of 0 means that the operation actually took milliseconds to perform. If you want to have microsecond resolution for this item in the access log, enter a value of 131328 (256+131072) in the nsslapd-accesslog-level configuration attribute.
LDAP Request Type
The LDAP request type indicates the type of LDAP request being issued by the LDAP client. Possible values are:
LDAP Response Type
The LDAP response type indicates the LDAP response being issued by the LDAP client. Possible values are:
REFERRAL=referral or search reference
Unindexed Search Indicator
The unindexed search indicator, notes=U, indicates that the search performed was unindexed, which means that the database itself had to be directly searched instead of the index file. Unindexed searches occur either when the All IDs Threshold was reached within the index file used for the search, when no index file existed, or when the index file was not configured in the way required by the search.
An unindexed search indicator is often accompanied by a large etime value, as unindexed searches are generally more time consuming.
Extended Operation OID
An extended operation OID, in this case either EXT oid="2.16.840.1.1137126.96.36.199" or EXT oid="2.16.840.1.1137188.8.131.52", provides the OID of the extended operation being performed. Table 3-1 provides the list of the LDAPv3 extended operations that are supported by Directory Server, and their OIDs.
Table 3-1 LDAPv3 Extended Operations Supported by Directory Server
Extended Operation Name
Directory Server 5.x Start Transport Layer Security (Start TLS)
Sent to initiate Transport Layer Security for authentication and encrypted communication.
Directory Server 5.x Start Replication Request
Sent by a replication initiator to indicate that a replication session is requested.
Directory Server 5.x Replication Response
Sent by a replication responder in response to a Start Replication Request Extended Operation or an End Replication Request Extended Operation.
Directory Server 5.x End Replication Request
Sent to indicate that a replication session is to be terminated.
Directory Server 5.x Replication Entry Request
Carries an entry, along with its state information (csn and UniqueIdentifier), and is used to perform a replica initialization.
Directory Server 5.x Bulk Import Start
Sent by the client to request a bulk import together with the suffix being imported to and sent by the server to indicate that the bulk import may begin.
Directory Server 5.x Bulk Import Finished
Sent by the client to signal the end of a bulk import and sent by the server to acknowledge it.
Change Sequence Number
The change sequence number, in this case csn=3b4c8cfb000000030000, is the replication change sequence number, indicating that replication is enabled on this particular naming context.
The abandon message, in this case, [06/Aug/2002:11:39:52 -0700] conn=12 op=2 ABANDON targetop=1 msgid=2 nentries=0 etime=0, indicates that an operation has been aborted, where nentries=0 indicates the number of entries sent before the operation was aborted, etime=0 indicates how much time (in seconds) had elapsed, and targetop=1 corresponds to an operation value from a previously initiated operation (that appears earlier in the access log).
There are two possible log ABANDON messages depending on whether the message ID succeeds in locating which operation was to be aborted or not. If the message ID succeeds in locating the operation (the targetop) then the log will read as above. However, if the message ID does not succeed in locating the operation or if the operation had already finished prior to the ABANDON request being sent, then the log will read as follows:
[06/Aug/2002:11:39:52 -0700] conn=12 op=2 ABANDON targetop=NOTFOUND msgid=2
where targetop=NOTFOUND indicates that the operation to be aborted was either an unknown operation or already complete.
The message ID, in this case msgid=2, is the LDAP operation identifier, as generated by the LDAP SDK client. The message ID may have a different value to the Directory Server Operation Number, but identifies the same operation. The message ID is used in the context of an ABANDON operation and tells the user which client operation is being abandoned.
The Directory Server operation number starts counting at 0. In the majority of LDAP SDK/client implementations the message ID number starts counting at 1. This explains why the message ID is frequently equal to the Directory Server operation number plus 1.
SASL Multi-Stage Bind Logging
Directory Server logs each stage in the multi-stage bind process and, where appropriate, the progress statement SASL bind in progress is included.
The authenticated DN (the DN used for access control decisions) is logged in the BIND result line and not in the bind request line:
[06/Aug/2002:11:39:55 -0700] conn=14 op=1 RESULT err=0 tag=97 nentries=0 etime=0 dn="uid=coulbeck,dc=example,dc=com"
For SASL binds, the DN value displayed in the BIND request line is not used by the server and is, therefore, not relevant. However, given that the authenticated DN is the DN which, for SASL binds, must be used for audit purposes, it is essential that this be clearly logged. Having this authenticated DN logged in the BIND result line avoids any confusion as to which DN is which.
Access Log Content for Additional Access Logging Levels
This section presents the additional access logging levels available in the Directory Server access log.
In Code Example 3-2, access logging level 512, which logs access to entries and referrals, is enabled. In this extract, 6 entries and 1 referral are returned in response to the search request in bold.
Code Example 3-2 Access Log Extract with Entry Access and Referral Logging Level (Level 512)
06/Aug/2002:16:43:02 +0200] conn=306 fd=60 slot=60 connection from 127.0.0.1 to 127.0.0.1
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 SRCH base="dc=example,dc=com" scope=2 filter="(description=*)" attrs=ALL
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="ou=Special Users,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="cn=Accounting Managers,ou=groups,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="cn=HR Managers,ou=groups,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="cn=QA Managers,ou=groups,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="cn=PD Managers,ou=groups,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 ENTRY dn="ou=Sun Java System Servers,dc=example,dc=com"
[06/Aug/2002:16:43:02 +0200] conn=306 op=0 REFERRAL
In Code Example 3-3, access logging level 4, which logs internal operations, is enabled.
Code Example 3-3 Access Log Extract with Internal Access Operations Level (Level 4)
[06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 SRCH base="cn=\22dc=example,dc=com\22,cn=mapping tree,cn=config"scope=0 filter="objectclass=nsMappingTree"attrs="nsslapd-referral" options=persistent
06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 RESULT err=0 tag=48 nentries=1etime=0
[06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 SRCH base="cn=\22dc=example,dc=com\22,cn=mapping tree,cn=config"
scope=0 filter="objectclass=nsMappingTree" attrs="nsslapd-state"
[06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 RESULT err=0 tag=48 nentries=1etime=0
Access log level 4 enables logging for internal operations which log the details of the search being performed, and the search base, scope, filter, and requested search attributes.
The connection description, in this case conn=Internal, indicates that the connection is an internal connection. The operation number op=-1 indicates that the operation was initiated internally.
The options description, in this case options=persistent, indicates that a persistent search is being performed. Persistent searches can be used as a form of monitoring. They can be configured to return changes to given configurations when changes occur.
The Sun Java System Directory Server access log distinguishes between persistent and regular searches. Some Directory Server releases prior to 5.2 did not make this distinction.
In Code Example 3-4, both access logging level 512 and 4 are enabled, which results in both internal access operations, as well as entry access and referrals being logged.
Code Example 3-4 Access Log Extract with Internal Access Operation, Entry Access and Referral Logging Levels (Levels 4+512)
[06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 ENTRY dn="cn=\22dc=example,dc=com\22, cn=mapping tree, cn=config"
[06/Aug/2002:16:45:46 +0200] conn=Internal op=-1 ENTRY dn="cn=\22dc=example,dc=com\22, cn=mapping tree, cn=config"
If you require further assistance in the investigation of your access log reports, please contact Sun Technical Support.
Common Connection Codes
A connection code is added to the closed log message to provide additional information about the connection closure. Table 3-2 summarizes the common connection codes.
Table 3-2 Common Connection Codes
The client has closed the connection without performing an UNBIND.
This connection code can have one of the following causes:
- The client has closed the connection without performing an UNBIND.
- The BER element was corrupt. If BER elements, which encapsulate data being sent over the wire, are corrupt when they are received, a B1 connection code is logged to the access log. BER elements can be corrupted by physical layer network problems or bad LDAP client operations, such as an LDAP client aborting before receiving all request results.
- The BER element is longer than the nsslapd-maxbersize attribute value. For information about the nsslapd-maxbersize attribute, see nsslapd-maxbersize (Maximum Message Size).
The BER element is longer than the nsslapd-maxbersize attribute value. For information about the nsslapd-maxbersize attribute, see nsslapd-maxbersize (Maximum Message Size).
A corrupt BER tag was encountered.
The server failed to flush data response back to client.
This code can occur when the client closes the connection to the server, before the server finished sending data to the client.
The client connection was closed by a custom plug-in. None of the plug-ins provided by Directory Server close a connection.
A closed connection or corrupt connection has been detected.
The server closed the client connection because it was idle for longer than the nsslapd-idletimeout attribute value. For information about the nsslapd-idletimeout attribute, see nsslapd-idletimeout (Idle Timeout).
The server closed the client connection because it was stalled for longer than the nsslapd-ioblocktimeout attribute value. For information about the nsslapd-ioblocktimeout attribute, see nsslapd-ioblocktimeout (IO Block Time Out).
This condition can occur for the following reasons:
The server closed the client connection because client sent an UNBIND request.
LDAP Result Codes
LDAP has a set of operation result codes with which you should be familiar. The following result codes may be generated by the LDAP server:
Table 3-3 LDAP Server Result Codes
Authentication method not supported
Strong authentication required
Partial results and referral received
Administrative limit exceeded
Unavailable critical extension
SASL bind in progress
No such attribute
Undefined attribute type
Type or value exists
No such object
Invalid DN syntax
Object is a leaf
Alias de-referencing problem
Server is busy
Server is unavailable
Server is unwilling to perform
Object class violation
Operation not permitted on a non-leaf entry
Operation not permitted on a RDN
Entry already exists
Cannot modify object class
Results too large
Affects multiple servers
Virtual list view error
The following result codes may be generated by LDAP clients:
Table 3-4 LDAP Client Result Codes
Cannot contact LDAP server
Unknown authentication method
Bad search filter
User cancelled operation
Bad parameter to an LDAP routine
Out of memory
Cannot connect to the LDAP server
Not supported by this version of LDAP
Requested LDAP control not found
No results returned
Additional results to return
Client detected loop
Referral hop limit exceeded