DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

slapo-accesslog(5)





NAME

       slapo-accesslog - Access Logging overlay to slapd


SYNOPSIS

       /etc/openldap/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.  Configura-
       tion 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 data-
              base  will  be  created  automatically  by this overlay. The log
              entries will be generated as the immediate children of the  suf-
              fix 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 opera-
              tions 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 dig-
              its, 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  index-
              ing 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 suc-
              cessful 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 with-
       out 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  general-
       izedTime  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  opera-
       tion  being logged, e.g.  add, delete, search, etc. For extended opera-
       tions, 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 oper-
       ation. 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 per-
       formed the operation.  This will usually be the same name as was estab-
       lished 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  opera-
       tion,  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  opera-
       tion.  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  unin-
       terpreted 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/openldap/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.

OpenLDAP 2.4.36                   2013/08/17                SLAPO-ACCESSLOG(5)

Man(1) output converted with man2html