Provided by: slapd_2.4.31-1+nmu2ubuntu8.5_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.  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.  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 bdb
            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 bdb
            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.

       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 ) )

       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.

       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 MUST 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 $ 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.