Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SLAPO-ACCESSLOG(5)	      File Formats Manual	    SLAPO-ACCESSLOG(5)

       slapo-accesslog - Access	Logging	overlay	to slapd


       The  Access  Logging  overlay  can  be used to record all accesses to a
       given backend database on another database. This	allows all of the  ac-
       tivity 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 read-
       ability whether viewed as LDIF or in raw	form.

       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 data-
	      base will	be created automatically by this overlay. The log  en-
	      tries  will be generated as the immediate	children of the	suffix

       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

		     abandon, bind, unbind

	      all    all operations

       logbase <operations> <baseDN>
	      Specify a	set of operations that will only be logged if they oc-
	      cur 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  en-
	      tries.  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 fil-
	      ters configured in logold.  Usually only	the  contents  of  at-
	      tributes	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 re-
	      quests whether they succeed or not. The default is FALSE.

	    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

       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  de-
       scribed 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:

	       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:

	       NAME 'auditObject'
	       DESC 'OpenLDAP request auditing'
	       SUP top STRUCTURAL
	       MUST ( reqStart $ reqType $ reqSession )
	       MAY ( reqDN $ reqAuthzID	$ reqControls $	reqRespControls	$
		   reqEnd $ reqResult $	reqMessage $ reqReferral $  reqEntryU-
	   UID ) )

       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.

       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  re-
       quest,  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  re-
       sponse, respectively. The attribute values are just uninterpreted octet

       The reqResult attribute is the numeric LDAP result code of  the	opera-
       tion, indicating	either success or a particular LDAP error code.	An er-
       ror 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:

	       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.

	       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.

	       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  us-
       ing DNs that reside in the current database will	be logged.

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

       For the Compare operation the reqAssertion attribute carries the	Attri-
       bute Value Assertion used in the	compare	request.

	       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.

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

       The Modify operation contains a description of modifications in the re-
       qMod attribute, which was already described above in the	Add operation.
       It  may	optionally  contain  the previous contents of any modified at-
       tributes	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.

	       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  at-
       tribute	is only	populated if the entry being modified matches the con-
       figured logold filter and contains attributes in	the logoldattr list.

	       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 at-
       tribute carries the filter used in the search request.  The reqAttr at-
       tribute lists the requested attributes if specific attributes were  re-
       quested.	 The reqEntries	attribute is the integer count of how many en-
       tries were returned by this search request.  The	reqSizeLimit and  req-
       TimeLimit  attributes indicate what limits were requested on the	search

	       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 at-
       tribute of the parent class. If any optional data was provided with the
       request,	 it  will be contained in the reqData attribute	as an uninter-
       preted octet string.

       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.

	      default slapd configuration file

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

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

OpenLDAP 2.6.1			  2022/01/20		    SLAPO-ACCESSLOG(5)


Want to link to this manual page? Use this URL:

home | help