Provided by: slapd_2.6.3+dfsg-1~exp1ubuntu2_amd64 bug

NAME

       slapo-accesslog - Access Logging overlay to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

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 audit schema (see below) to assure their readability whether viewed as LDIF or
       in raw form.

CONFIGURATION

       These  slapd.conf  options  apply to the Access Logging overlay.  They should appear after
       the overlay directive.

       logdb <suffix>
              Specify the suffix of a database to be used  for  storing  the  log  records.   The
              specified  database must be defined elsewhere in the configuration and must support
              an ordered return of results such as slapd-mdb(5) The access controls  on  the  log
              database  should  prevent general access. The suffix entry of the log database will
              be created automatically by this overlay. The log entries will be generated as  the
              immediate children of the suffix entry.

       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:

              writes add, delete, modify, modrdn

              reads  compare, search

              session
                     abandon, bind, unbind

              all    all operations

       logbase <operations> <baseDN>
              Specify a set of operations that will only be logged if they occur under a specific
              subtree of the database. The operation types are as above for the  logops  setting,
              and delimited by a '|' character.

       logold <filter>
              Specify  a  filter  for matching against Deleted and Modified entries. If the entry
              matches the filter, the old contents of the entry will be  logged  along  with  the
              current request.

       logoldattr <attr> ...
              Specify  a  list  of  attributes whose old contents are always logged in Modify and
              ModRDN requests that match any of the filters configured in logold.   Usually  only
              the  contents  of attributes that were actually modified will be logged; by default
              no old attributes are logged for ModRDN requests.

       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 age and interval are specified
              as a  time  span  in  days,  hours,  minutes,  and  seconds.  The  time  format  is
              [ddd+]hh:mm[:ss]  i.e.,  the days and seconds components are optional but hours and
              minutes are required. Except for days, which can be up to 5  digits,  each  numeric
              field must be exactly two digits. For example
                     logpurge 2+00:00 1+00:00
              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 reqStart attribute will greatly benefit the performance of the purge operation.

       logsuccess TRUE | FALSE
              If set to TRUE then log records will only be  generated  for  successful  requests,
              i.e.,  requests  that  produce  a  result  code of 0 (LDAP_SUCCESS).  If FALSE, log
              records are generated for all requests whether they succeed or not. The default  is
              FALSE.

EXAMPLES

            database mdb
            suffix dc=example,dc=com
            ...
            overlay accesslog
            logdb cn=log
            logops writes reads
            logbase search|compare ou=testing,dc=example,dc=com
            logold (objectclass=person)

            database mdb
            suffix cn=log
            ...
            index reqStart eq
            access to *
              by dn.base="cn=admin,dc=example,dc=com" read

SCHEMA

       The  accesslog  overlay  utilizes  the  "audit"  schema  described herein.  This schema is
       specifically designed for accesslog auditing and is not intended to be used otherwise.  It
       is  also  noted that the schema described here is a work in progress, and hence subject to
       change without notice.  The schema is loaded automatically by the overlay.

       The schema includes a number of object classes and associated attribute types as described
       below.

       The  root entry of the underlying accesslog database makes use of the auditContainer class
       which is as follows:

           (  1.3.6.1.4.1.4203.666.11.5.2.0
               NAME 'auditContainer'
               DESC 'AuditLog container'
               SUP top STRUCTURAL
               MAY ( cn $ reqStart $ reqEnd ) )

       There is a basic auditObject class from which two additional classes, auditReadObject  and
       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 auditObject class is as follows:

           (  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 $ reqReferral $ reqEntryUUID ) )

       Note that all of the OIDs used in the logging schema currently reside under  the  OpenLDAP
       Experimental  branch. It is anticipated that they will migrate to a Standard branch in the
       future.

       An overview of the attributes follows: reqStart and reqEnd provide the start and end  time
       of the operation, respectively. They use generalizedTime syntax. The reqStart attribute is
       also used as the RDN for each log entry.

       The reqType attribute is a simple string containing the type of  operation  being  logged,
       e.g.  add, delete, search, etc. For extended operations, the type also includes the OID of
       the extended operation, e.g.  extended(1.1.1.1)

       The 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 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 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 reqControls and 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 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 reqMessage attribute.

       The reqReferral attribute carries any referrals that were returned with the result of  the
       request.

       The  reqEntryUUID  attribute records the entryUUID attribute of the entry operated on, for
       an Add request, this is the entryUUID of the newly created entry.

       Operation-specific classes are defined with additional attributes  to  carry  all  of  the
       relevant parameters associated with the operation:

           (  1.3.6.1.4.1.4203.666.11.5.2.4
               NAME 'auditAbandon'
               DESC 'Abandon operation'
               SUP auditObject STRUCTURAL
               MUST reqId )

       For  the Abandon operation the reqId attribute contains the message ID of the request that
       was abandoned.

           (  1.3.6.1.4.1.4203.666.11.5.2.5
               NAME 'auditAdd'
               DESC 'Add operation'
               SUP auditWriteObject STRUCTURAL
               MUST reqMod )

       The Add class inherits from the auditWriteObject class. The Add  and  Modify  classes  are
       very  similar.  The  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
              attribute:<+|-|=|#> [ value]
       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.

           (  1.3.6.1.4.1.4203.666.11.5.2.6
               NAME 'auditBind'
               DESC 'Bind operation'
               SUP auditObject STRUCTURAL
               MUST ( reqVersion $ reqMethod ) )

       The Bind class includes the reqVersion attribute which contains the LDAP protocol  version
       specified  in  the  Bind as well as the reqMethod attribute which contains the Bind Method
       used in the Bind. This will be the string SIMPLE for LDAP Simple Binds or 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.

           (  1.3.6.1.4.1.4203.666.11.5.2.7
               NAME 'auditCompare'
               DESC 'Compare operation'
               SUP auditObject STRUCTURAL
               MUST reqAssertion )

       For the Compare operation the reqAssertion attribute carries the Attribute Value Assertion
       used in the compare request.

           (  1.3.6.1.4.1.4203.666.11.5.2.8
               NAME 'auditDelete'
               DESC 'Delete operation'
               SUP auditWriteObject STRUCTURAL
               MAY reqOld )

       The  Delete  operation  needs  no  further  parameters.  However, the reqOld attribute may
       optionally be used to record the contents of the entry prior to its deletion.  The  values
       are formatted as
              attribute: value
       The  reqOld  attribute is only populated if the entry being deleted matches the configured
       logold filter.

           (  1.3.6.1.4.1.4203.666.11.5.2.9
               NAME 'auditModify'
               DESC 'Modify operation'
               SUP auditWriteObject STRUCTURAL
               MAY ( reqOld $ reqMod ) )

       The Modify operation contains a description of  modifications  in  the  reqMod  attribute,
       which  was  already  described  above  in the Add operation. It may optionally contain the
       previous contents of any modified attributes in  the  reqOld  attribute,  using  the  same
       format  as  described  above  for  the  Delete  operation.   The  reqOld attribute is only
       populated if the entry being modified matches the configured logold filter.

           (  1.3.6.1.4.1.4203.666.11.5.2.10
               NAME 'auditModRDN'
               DESC 'ModRDN operation'
               SUP auditWriteObject STRUCTURAL
               MUST ( reqNewRDN $ reqDeleteOldRDN )
               MAY ( reqNewSuperior $ reqMod $ reqOld ) )

       The ModRDN class uses the reqNewRDN attribute to carry the new RDN of  the  request.   The
       reqDeleteOldRDN  attribute is a Boolean value showing TRUE if the old RDN was deleted from
       the entry, or FALSE if the old RDN was preserved.  The  reqNewSuperior  attribute  carries
       the  DN  of  the  new  parent  entry  if the request specified the new parent.  The reqOld
       attribute is only populated if the entry being  modified  matches  the  configured  logold
       filter and contains attributes in the logoldattr list.

           (  1.3.6.1.4.1.4203.666.11.5.2.11
               NAME 'auditSearch'
               DESC 'Search operation'
               SUP auditReadObject STRUCTURAL
               MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly )
               MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $
                     reqTimeLimit ) )

       For  the  Search  class  the  reqScope attribute contains the scope of the original search
       request, using the values specified for the LDAP URL format.  I.e.   base,  one,  sub,  or
       subord.   The  reqDerefAliases  attribute  is one of never, finding, searching, or always,
       denoting how aliases will be processed during the search.  The reqAttrsOnly attribute is a
       Boolean  value showing TRUE if only attribute names were requested, or FALSE if attributes
       and their values were requested.  The reqFilter attribute carries the filter used  in  the
       search  request.   The  reqAttr  attribute  lists  the  requested  attributes  if specific
       attributes were requested.  The reqEntries attribute is the  integer  count  of  how  many
       entries  were  returned  by  this  search  request.   The  reqSizeLimit  and  reqTimeLimit
       attributes indicate what limits were requested on the search operation.

           (  1.3.6.1.4.1.4203.666.11.5.2.12
               NAME 'auditExtended'
               DESC 'Extended operation'
               SUP auditObject STRUCTURAL
               MAY reqData )

       The Extended class represents an LDAP Extended Operation. As noted above, the  actual  OID
       of the operation is included in the reqType attribute of the parent class. If any optional
       data was provided with the request, it will be contained in the reqData  attribute  as  an
       uninterpreted octet string.

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.

FILES

       /etc/ldap/slapd.conf
              default slapd configuration file

SEE ALSO

       slapd.conf(5), slapd-config(5).

ACKNOWLEDGEMENTS

       This module was written in 2005 by Howard Chu of Symas Corporation.