DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

slapo-accesslog(5)




SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)


NAME

     slapo-accesslog - Access Logging overlay


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 log-
     ging 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  log-
     ging  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  over-
     lay.  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 have
          already been configured in a prior section of the  con-
          fig  file,  and  it  must have a rootDN configured. The
          access controls on the log database should prevent gen-
          eral write 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 avail-
          able:

          writes
               add, delete, modify, modrdn

          reads
               compare, search

          session
               abandon, bind, unbind

          all  all operations

     logold <filter>

OpenLDAP 2.3.27      Last change: 2006/08/19                    1

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)

          Specify a filter for matching against Deleted and Modi-
          fied  entries. If the entry matches the filter, the old
          contents of the entry will be  logged  along  with  the
          current request.

     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 attri-
          butes, 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 cn=log
          ...
          index reqStart eq

          database bdb
          suffix dc=example,dc=com
          ...
          overlay accesslog
          logdb cn=log
          logops writes reads
          logold (objectclass=person)


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  describe  here  is a work in

OpenLDAP 2.3.27      Last change: 2006/08/19                    2

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)

     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  associ-
     ated 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 auditOb-
     ject 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 $ reqRespCon-
         trols $
                 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, respec-
     tively. They use generalizedTime syntax. The reqStart attri-
     bute 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 iden-
     tifier  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

OpenLDAP 2.3.27      Last change: 2006/08/19                    3

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)

     same name as was established at the start of a session by  a
     Bind  request  (if  any)  but may be altered in various cir-
     cumstances.

     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 associ-
     ated 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 attri-
     bute 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

OpenLDAP 2.3.27      Last change: 2006/08/19                    4

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)

             MUST ( reqVersion $ reqMethod ) )
     The Bind class includes the reqVersion attribute which  con-
     tains  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

OpenLDAP 2.3.27      Last change: 2006/08/19                    5

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)

             MUST ( reqNewRDN $ reqDeleteOldRDN )
             MAY reqNewSuperior )
     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.

         (  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  $  reqSizeL-
         imit $
                   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 reqSizeL-
     imit  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 replica-
     tion mechanism, as well as for security/audit  logging  pur-
     poses.

OpenLDAP 2.3.27      Last change: 2006/08/19                    6

SLAPO-ACCESSLOG(5)        FILE FORMATS         SLAPO-ACCESSLOG(5)


FILES

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


SEE ALSO

     slapd.conf(5).


ACKNOWLEDGEMENTS

     This module was written in 2005 by Howard Chu of Symas  Cor-
     poration.

OpenLDAP 2.3.27      Last change: 2006/08/19                    7


Man(1) output converted with man2html