--- /dev/null
+.TH SLAPO-ACCESSLOG 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2005 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
+.SH NAME
+slapo-accesslog \- Access Logging overlay
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+The Access Logging overlay can be used to record all accesses to a given
+backend database on another database. This allows all of the activity on
+a given database to be reviewed using arbitrary LDAP queries, instead of
+just logging to local flat text files. Configuration options are available
+for selecting a subset of operation types to log, and to automatically
+prune older log records from the logging database. Log records are stored
+with a custom schema to assure their readability whether viewed as LDIF
+or in raw form.
+.SH CONFIGURATION
+These
+.B slapd.conf
+options apply to the Access Logging overlay.
+They should appear after the
+.B overlay
+directive and before any subsequent
+.B database
+directive.
+.TP
+.B logdb <suffix>
+Specify the suffix of a database to be used for storing the log records.
+The specified database must have already been configured in a prior section
+of the config file. The suffix entry of the database must also already
+exist. The log entries will be generated as the immediate children of the
+suffix entry.
+.TP
+.B logops <operations>
+Specify which types of operations to log. The valid operation types are
+abandon, add, bind, compare, delete, extended, modify, modrdn, search,
+and unbind. Aliases for common sets of operations are also available:
+.RS
+.TP
+.B writes
+add, delete, modify, modrdn
+.TP
+.B reads
+compare, search
+.TP
+.B session
+abandon, bind, unbind
+.TP
+.B all
+all operations
+.RE
+.TP
+.B logpurge <age> <interval>
+Specify the maximum age for log entries to be retained in the database,
+and how often to scan the database for old entries. Both the
+.B age
+and
+.B interval
+are specified as a time span in days, hours, minutes, and seconds. The
+time format is [dd+]hh:mm[:ss] i.e., the days and seconds components are
+optional but hours and minutes are required. Each numeric field must be
+exactly two digits. For example
+.RS
+.RS
+.PD 0
+.TP
+logpurge 02+00:00 01+00:00
+.RE
+.PD
+would specify that the log database should be scanned every day for old
+entries, and entries older than two days should be deleted. When using a
+log database that supports ordered indexing on generalizedTime attributes,
+specifying an eq index on the
+.B reqStart
+attribute will greatly benefit the performance of the purge operation.
+
+.SH EXAMPLES
+.LP
+.nf
+ database bdb
+ suffix cn=log
+ \...
+ index reqStart eq
+
+ database bdb
+ suffix dc=example,dc=com
+ \...
+ overlay accesslog
+ logdb cn=log
+ logops writes reads
+.fi
+
+.SH OBJECT CLASSES
+The
+.B accesslog
+overlay defines a number of object classes for use in the logs. There is
+a basic
+.B auditObject
+class from which two additional classes,
+.B auditReadObject
+and
+.B auditWriteObject
+are derived. Object classes for each type of LDAP operation are further
+derived from these classes. This object class hierarchy is designed to
+allow flexible yet efficient searches of the log based on either a specific
+operation type's class, or on more general classifications. The definition
+of the
+.B auditObject
+class is as follows:
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.1
+ NAME 'auditObject'
+ DESC 'OpenLDAP request auditing'
+ SUP top STRUCTURAL
+ MUST ( reqStart $ reqType $ reqSession )
+ MAY ( reqDN $ reqAuthzID $ reqControls $ reqRespControls $
+ reqEnd $ reqResult $ reqMessage ) )
+.RE
+.P
+Note that all of the OIDs used in the logging schema currently reside
+under the OpenLDAP Experimental branch. It is anticipated that thay
+will migrate to a Standard branch in the future.
+
+An overview of the attributes follows:
+.B reqStart
+and
+.B reqEnd
+provide the start and end time of the operation, respectively. They use
+generalizedTime syntax. The
+.B reqStart
+attribute is also used as the RDN for each log entry.
+
+The
+.B reqType
+attribute is a simple string containing the type of operation
+being logged, e.g.
+.BR add ,
+.BR delete ,
+.BR search ,
+etc. For extended operations, the type also includes the OID of the
+extended operation, e.g.
+.B extended(1.2.3.4.1)
+
+The
+.B reqSession
+attribute is an implementation-specific identifier that is common to
+all the operations associated with the same LDAP session. Currently this
+is slapd's internal connection ID, stored in decimal.
+
+The
+.B reqDN
+attribute is the distinguishedName of the target of the operation. E.g., for
+a Bind request, this is the Bind DN. For an Add request, this is the DN
+of the entry being added. For a Search request, this is the base DN of
+the search.
+
+The
+.B reqAuthzID
+attribute is the distinguishedName of the user that performed the operation.
+This will usually be the same name as was established at the start of a
+session by a Bind request (if any) but may be altered in various
+circumstances.
+
+The
+.BR reqControls and
+.B reqRespControls
+attributes carry any controls sent by the client on the request and returned
+by the server in the response, respectively. The attribute values are just
+uninterpreted octet strings.
+
+The
+.B reqResult
+attribute is the numeric LDAP result code of the operation, indicating
+either success or a particular LDAP error code. An error code may be
+accompanied by a text error message which will be recorded in the
+.B reqMessage
+attribute.
+
+Operation-specific classes are defined with additional attributes to carry
+all of the relevant parameters associated with the operation:
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.4
+ NAME 'auditAbandon'
+ DESC 'Abandon operation'
+ SUP auditObject STRUCTURAL
+ MUST reqId )
+.RE
+.P
+For the
+.B Abandon
+operation the
+.B reqId
+attribute contains the message ID of the request that was abandoned.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.5
+ NAME 'auditAdd'
+ DESC 'Add operation'
+ SUP auditWriteObject STRUCTURAL
+ MUST reqMod )
+.RE
+.P
+The
+.B Add
+class inherits from the
+.B auditWriteObject
+class. The Add and Modify classes are essentially the same. The
+.B reqMod
+attribute carries all of the attributes of the original entry being added.
+(Or in the case of a Modify operation, all of the modifications being
+performed.) The values are formatted as
+.RS
+.RS
+.PD 0
+.TP
+attribute:<+|-|=|#> [ value]
+.RE
+.PD
+Where '+' indicates an Add of a value, '-' for Delete, '=' for Replace,
+and '#' for Increment. In an Add operation, all of the reqMod values will
+have the '+' designator.
+.RE
+.P
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.6
+ NAME 'auditBind'
+ DESC 'Bind operation'
+ SUP auditObject STRUCTURAL
+ MUST reqMethod )
+.RE
+.P
+The
+.B Bind
+class just adds the
+.B reqMethod
+attribute which contains the Bind Method used in the Bind. This will be
+the string
+.B SIMPLE
+for LDAP Simple Binds or
+.B SASL(<mech>)
+for SASL Binds.
+Note that unless configured as a global overlay, only Simple Binds using
+DNs that reside in the current database will be logged.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.7
+ NAME 'auditCompare'
+ DESC 'Compare operation'
+ SUP auditObject STRUCTURAL
+ MUST reqAssertion )
+.RE
+.P
+For the
+.B Compare
+operation the
+.B reqAssertion
+attribute carries the Attribute Value Assertion used in the compare request.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.8
+ NAME 'auditModify'
+ DESC 'Modify operation'
+ SUP auditWriteObject STRUCTURAL
+ MUST reqMod )
+.RE
+.P
+The
+.B Modify
+operation has already been described.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.9
+ NAME 'auditModRDN'
+ DESC 'ModRDN operation'
+ SUP auditWriteObject STRUCTURAL
+ MUST ( reqNewRDN $ reqDeleteOldRDN )
+ MAY reqNewSuperior )
+.RE
+.P
+The
+.B ModRDN
+class uses the
+.B reqNewRDN
+attribute to carry the new RDN of the request.
+The
+.B reqDeleteOldRDN
+attribute is a Boolean value showing
+.B TRUE
+if the old RDN was deleted from the entry, or
+.B FALSE
+if the old RDN was preserved.
+The
+.B reqNewSuperior
+attribute carries the DN of the new parent entry if the request specified
+the new parent.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.10
+ NAME 'auditSearch'
+ DESC 'Search operation'
+ SUP auditReadObject STRUCTURAL
+ MUST ( reqScope $ reqAttrsOnly )
+ MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $
+ reqTimeLimit ) )
+.RE
+.P
+For the
+.B Search
+class the
+.B reqScope
+attribute contains the scope of the original search request, i.e.
+.BR base ,
+.BR onelevel ,
+.BR subtree ,
+or
+.BR subordinate .
+The
+.B reqAttrsOnly
+attribute is a Boolean value showing
+.B TRUE
+if only attribute names were requested, or
+.B FALSE
+if attributes and their values were requested.
+The
+.B reqFilter
+attribute carries the filter used in the search request.
+The
+.B reqAttr
+attribute lists the requested attributes if specific attributes were
+requested.
+The
+.B reqEntries
+attribute is the integer count of how many entries were returned by
+this search request.
+The
+.B reqSizeLimit
+and
+.B reqTimeLimit
+attributes indicate what limits were requested on the search operation.
+
+.LP
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.5.2.11
+ NAME 'auditExtended'
+ DESC 'Extended operation'
+ SUP auditObject STRUCTURAL
+ MAY reqData )
+.RE
+.P
+The
+.B Extended
+class represents an LDAP Extended Operation. As noted above, the actual OID of
+the operation is included in the
+.B reqType
+attribute of the parent class. If any optional data was provided with the
+request, it will be contained in the
+.B reqData
+attribute as an uninterpreted octet string.
+
+.SH NOTES
+The Access Log implemented by this overlay may be used for a variety of
+other tasks, e.g. as a ChangeLog for a replication mechanism, as well
+as for security/audit logging purposes.
+
+.SH FILES
+.TP
+ETCDIR/slapd.conf
+default slapd configuration file
+.SH SEE ALSO
+.BR slapd.conf (5).
+
+.SH ACKNOWLEDGEMENTS
+.P
+This module was written in 2005 by Howard Chu of Symas Corporation.
"SUP auditObject STRUCTURAL )", &log_ocs[LOG_EN_DELETE] },
{ "( " LOG_SCHEMA_OC ".4 NAME 'auditAbandon' "
"DESC 'Abandon operation' "
- "SUP auditReadObject STRUCTURAL "
+ "SUP auditObject STRUCTURAL "
"MUST reqId )", &log_ocs[LOG_EN_ABANDON] },
{ "( " LOG_SCHEMA_OC ".5 NAME 'auditAdd' "
"DESC 'Add operation' "
"MUST reqMod )", &log_ocs[LOG_EN_ADD] },
{ "( " LOG_SCHEMA_OC ".6 NAME 'auditBind' "
"DESC 'Bind operation' "
- "SUP auditReadObject STRUCTURAL "
+ "SUP auditObject STRUCTURAL "
"MUST reqMethod )", &log_ocs[LOG_EN_BIND] },
{ "( " LOG_SCHEMA_OC ".7 NAME 'auditCompare' "
"DESC 'Compare operation' "
"SUP auditReadObject STRUCTURAL "
"MUST reqAssertion )", &log_ocs[LOG_EN_COMPARE] },
{ "( " LOG_SCHEMA_OC ".8 NAME 'auditModify' "
- "DESC 'Add or Modify operation' "
+ "DESC 'Modify operation' "
"SUP auditWriteObject STRUCTURAL "
"MUST reqMod )", &log_ocs[LOG_EN_MODIFY] },
{ "( " LOG_SCHEMA_OC ".9 NAME 'auditModRDN' "
"reqTimeLimit ) )", &log_ocs[LOG_EN_SEARCH] },
{ "( " LOG_SCHEMA_OC ".11 NAME 'auditExtended' "
"DESC 'Extended operation' "
- "SUP auditReadObject STRUCTURAL "
+ "SUP auditObject STRUCTURAL "
"MAY reqData )", &log_ocs[LOG_EN_EXTENDED] },
{ NULL, NULL }
};
projects / openldap / commitdiff