1SLAPO-ACCESSLOG(5)            File Formats Manual           SLAPO-ACCESSLOG(5)
2
3
4

NAME

6       slapo-accesslog - Access Logging overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The  Access  Logging  overlay  can  be used to record all accesses to a
13       given backend database on another database.  This  allows  all  of  the
14       activity  on  a  given  database  to  be  reviewed using arbitrary LDAP
15       queries, instead of just logging to local flat text  files.  Configura‐
16       tion options are available for selecting a subset of operation types to
17       log, and to automatically prune older  log  records  from  the  logging
18       database.   Log  records  are  stored  with audit schema (see below) to
19       assure their readability whether viewed as LDIF or in raw form.
20

CONFIGURATION

22       These slapd.conf options apply to the  Access  Logging  overlay.   They
23       should appear after the overlay directive.
24
25       logdb <suffix>
26              Specify  the suffix of a database to be used for storing the log
27              records.  The specified database must be  defined  elsewhere  in
28              the  configuration.   The  access  controls  on the log database
29              should prevent general access. The suffix entry of the log data‐
30              base  will  be  created  automatically  by this overlay. The log
31              entries will be generated as the immediate children of the  suf‐
32              fix entry.
33
34       logops <operations>
35              Specify  which  types  of operations to log. The valid operation
36              types are abandon, add, bind, compare, delete, extended, modify,
37              modrdn,  search,  and  unbind. Aliases for common sets of opera‐
38              tions are also available:
39
40              writes add, delete, modify, modrdn
41
42              reads  compare, search
43
44              session
45                     abandon, bind, unbind
46
47              all    all operations
48
49       logbase <operations> <baseDN>
50              Specify a set of operations that will only  be  logged  if  they
51              occur  under  a  specific subtree of the database. The operation
52              types are as above for the logops setting, and  delimited  by  a
53              '|' character.
54
55       logold <filter>
56              Specify  a  filter  for  matching  against  Deleted and Modified
57              entries. If the entry matches the filter, the  old  contents  of
58              the entry will be logged along with the current request.
59
60       logoldattr <attr> ...
61              Specify  a  list  of  attributes  whose  old contents are always
62              logged in Modify and ModRDN requests. Usually only the  contents
63              of  attributes  that  were  actually modified will be logged; by
64              default no old attributes are logged for ModRDN requests.
65
66       logpurge <age> <interval>
67              Specify the maximum age for log entries to be  retained  in  the
68              database,  and  how  often to scan the database for old entries.
69              Both the age and interval are specified as a time span in  days,
70              hours, minutes, and seconds. The time format is [ddd+]hh:mm[:ss]
71              i.e., the days and seconds components are optional but hours and
72              minutes are required. Except for days, which can be up to 5 dig‐
73              its, each numeric field must be exactly two digits. For example
74                     logpurge 2+00:00 1+00:00
75              would specify that the log database should be scanned every  day
76              for  old  entries,  and  entries  older  than two days should be
77              deleted. When using a log database that supports ordered  index‐
78              ing on generalizedTime attributes, specifying an eq index on the
79              reqStart attribute will greatly benefit the performance  of  the
80              purge operation.
81
82       logsuccess TRUE | FALSE
83              If  set to TRUE then log records will only be generated for suc‐
84              cessful requests, i.e., requests that produce a result code of 0
85              (LDAP_SUCCESS).   If  FALSE,  log  records are generated for all
86              requests whether they succeed or not. The default is FALSE.
87
88

EXAMPLES

90            database bdb
91            suffix dc=example,dc=com
92            ...
93            overlay accesslog
94            logdb cn=log
95            logops writes reads
96            logbase search|compare ou=testing,dc=example,dc=com
97            logold (objectclass=person)
98
99            database bdb
100            suffix cn=log
101            ...
102            index reqStart eq
103            access to *
104              by dn.base="cn=admin,dc=example,dc=com" read
105
106

SCHEMA

108       The accesslog overlay utilizes the  "audit"  schema  described  herein.
109       This  schema is specifically designed for accesslog auditing and is not
110       intended to be used otherwise.   It  is  also  noted  that  the  schema
111       described here is a work in progress, and hence subject to change with‐
112       out notice.  The schema is loaded automatically by the overlay.
113
114       The schema includes a number of object classes and associated attribute
115       types as described below.
116
117       There  is  a basic auditObject class from which two additional classes,
118       auditReadObject and auditWriteObject are derived.  Object  classes  for
119       each  type  of  LDAP  operation are further derived from these classes.
120       This object class hierarchy is designed to allow flexible yet efficient
121       searches  of the log based on either a specific operation type's class,
122       or on more general classifications. The definition of  the  auditObject
123       class is as follows:
124
125           (  1.3.6.1.4.1.4203.666.11.5.2.1
126               NAME 'auditObject'
127               DESC 'OpenLDAP request auditing'
128               SUP top STRUCTURAL
129               MUST ( reqStart $ reqType $ reqSession )
130               MAY ( reqDN $ reqAuthzID $ reqControls $ reqRespControls $
131                   reqEnd $ reqResult $ reqMessage $ reqReferral ) )
132
133       Note  that  all of the OIDs used in the logging schema currently reside
134       under the OpenLDAP Experimental branch. It  is  anticipated  that  they
135       will migrate to a Standard branch in the future.
136
137       An  overview of the attributes follows: reqStart and reqEnd provide the
138       start and end time of the operation, respectively.  They  use  general‐
139       izedTime  syntax.  The  reqStart  attribute is also used as the RDN for
140       each log entry.
141
142       The reqType attribute is a simple string containing the type of  opera‐
143       tion  being logged, e.g.  add, delete, search, etc. For extended opera‐
144       tions, the type also includes the OID of the extended  operation,  e.g.
145       extended(1.1.1.1)
146
147       The  reqSession attribute is an implementation-specific identifier that
148       is common to all the operations associated with the same LDAP  session.
149       Currently this is slapd's internal connection ID, stored in decimal.
150
151       The reqDN attribute is the distinguishedName of the target of the oper‐
152       ation. E.g., for a Bind request, this  is  the  Bind  DN.  For  an  Add
153       request, this is the DN of the entry being added. For a Search request,
154       this is the base DN of the search.
155
156       The reqAuthzID attribute is the distinguishedName of the user that per‐
157       formed the operation.  This will usually be the same name as was estab‐
158       lished at the start of a session by a Bind request (if any) but may  be
159       altered in various circumstances.
160
161       The  reqControls and reqRespControls attributes carry any controls sent
162       by the client on  the  request  and  returned  by  the  server  in  the
163       response,  respectively.  The  attribute  values are just uninterpreted
164       octet strings.
165
166       The reqResult attribute is the numeric LDAP result code of  the  opera‐
167       tion,  indicating  either  success  or a particular LDAP error code. An
168       error code may be accompanied by a text error  message  which  will  be
169       recorded in the reqMessage attribute.
170
171       The reqReferral attribute carries any referrals that were returned with
172       the result of the request.
173
174       Operation-specific classes are defined with  additional  attributes  to
175       carry all of the relevant parameters associated with the operation:
176
177
178           (  1.3.6.1.4.1.4203.666.11.5.2.4
179               NAME 'auditAbandon'
180               DESC 'Abandon operation'
181               SUP auditObject STRUCTURAL
182               MUST reqId )
183
184       For  the  Abandon operation the reqId attribute contains the message ID
185       of the request that was abandoned.
186
187
188           (  1.3.6.1.4.1.4203.666.11.5.2.5
189               NAME 'auditAdd'
190               DESC 'Add operation'
191               SUP auditWriteObject STRUCTURAL
192               MUST reqMod )
193
194       The Add class inherits from the auditWriteObject  class.  The  Add  and
195       Modify  classes  are  very similar. The reqMod attribute carries all of
196       the attributes of the original entry being added.  (Or in the case of a
197       Modify operation, all of the modifications being performed.) The values
198       are formatted as
199              attribute:<+|-|=|#> [ value]
200       Where '+' indicates an Add of a value, '-' for Delete, '=' for Replace,
201       and  '#'  for  Increment. In an Add operation, all of the reqMod values
202       will have the '+' designator.
203
204           (  1.3.6.1.4.1.4203.666.11.5.2.6
205               NAME 'auditBind'
206               DESC 'Bind operation'
207               SUP auditObject STRUCTURAL
208               MUST ( reqVersion $ reqMethod ) )
209
210       The Bind class includes the reqVersion  attribute  which  contains  the
211       LDAP  protocol  version  specified in the Bind as well as the reqMethod
212       attribute which contains the Bind Method used in the Bind. This will be
213       the string SIMPLE for LDAP Simple Binds or SASL(<mech>) for SASL Binds.
214       Note that unless configured as a  global  overlay,  only  Simple  Binds
215       using DNs that reside in the current database will be logged.
216
217
218           (  1.3.6.1.4.1.4203.666.11.5.2.7
219               NAME 'auditCompare'
220               DESC 'Compare operation'
221               SUP auditObject STRUCTURAL
222               MUST reqAssertion )
223
224       For  the  Compare  operation  the  reqAssertion  attribute  carries the
225       Attribute Value Assertion used in the compare request.
226
227
228           (  1.3.6.1.4.1.4203.666.11.5.2.8
229               NAME 'auditDelete'
230               DESC 'Delete operation'
231               SUP auditWriteObject STRUCTURAL
232               MAY reqOld )
233
234       The Delete operation needs no further parameters. However,  the  reqOld
235       attribute  may  optionally  be used to record the contents of the entry
236       prior to its deletion. The values are formatted as
237              attribute: value
238       The reqOld attribute is only  populated  if  the  entry  being  deleted
239       matches the configured logold filter.
240
241
242           (  1.3.6.1.4.1.4203.666.11.5.2.9
243               NAME 'auditModify'
244               DESC 'Modify operation'
245               SUP auditWriteObject STRUCTURAL
246               MAY reqOld MUST reqMod )
247
248       The  Modify  operation  contains  a description of modifications in the
249       reqMod attribute, which was already described above in the  Add  opera‐
250       tion.  It  may optionally contain the previous contents of any modified
251       attributes in the reqOld attribute, using the same format as  described
252       above for the Delete operation.  The reqOld attribute is only populated
253       if the entry being modified matches the configured logold filter.
254
255
256           (  1.3.6.1.4.1.4203.666.11.5.2.10
257               NAME 'auditModRDN'
258               DESC 'ModRDN operation'
259               SUP auditWriteObject STRUCTURAL
260               MUST ( reqNewRDN $ reqDeleteOldRDN )
261               MAY ( reqNewSuperior $ reqOld ) )
262
263       The ModRDN class uses the reqNewRDN attribute to carry the new  RDN  of
264       the  request.  The reqDeleteOldRDN attribute is a Boolean value showing
265       TRUE if the old RDN was deleted from the entry, or FALSE if the old RDN
266       was  preserved.  The reqNewSuperior attribute carries the DN of the new
267       parent entry if the request  specified  the  new  parent.   The  reqOld
268       attribute  is  only  populated  if the entry being modified matches the
269       configured logold filter and  contains  attributes  in  the  logoldattr
270       list.
271
272
273           (  1.3.6.1.4.1.4203.666.11.5.2.11
274               NAME 'auditSearch'
275               DESC 'Search operation'
276               SUP auditReadObject STRUCTURAL
277               MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly )
278               MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $
279                     reqTimeLimit ) )
280
281       For  the  Search class the reqScope attribute contains the scope of the
282       original search request, using the values specified for  the  LDAP  URL
283       format. I.e.  base, one, sub, or subord.  The reqDerefAliases attribute
284       is one of never, finding, searching, or always,  denoting  how  aliases
285       will  be  processed during the search.  The reqAttrsOnly attribute is a
286       Boolean value showing TRUE if only attribute names were  requested,  or
287       FALSE  if  attributes  and  their values were requested.  The reqFilter
288       attribute carries the filter used in the search request.   The  reqAttr
289       attribute  lists  the  requested attributes if specific attributes were
290       requested.  The reqEntries attribute is the integer count of  how  many
291       entries  were  returned  by  this search request.  The reqSizeLimit and
292       reqTimeLimit attributes indicate what  limits  were  requested  on  the
293       search operation.
294
295
296           (  1.3.6.1.4.1.4203.666.11.5.2.12
297               NAME 'auditExtended'
298               DESC 'Extended operation'
299               SUP auditObject STRUCTURAL
300               MAY reqData )
301
302       The  Extended  class  represents  an  LDAP Extended Operation. As noted
303       above, the actual OID of the  operation  is  included  in  the  reqType
304       attribute  of  the parent class. If any optional data was provided with
305       the request, it will be contained in the reqData attribute as an  unin‐
306       terpreted octet string.
307
308

NOTES

310       The Access Log implemented by this overlay may be used for a variety of
311       other tasks, e.g. as a ChangeLog for a replication mechanism,  as  well
312       as for security/audit logging purposes.
313
314

FILES

316       /etc/openldap/slapd.conf
317              default slapd configuration file
318

SEE ALSO

320       slapd.conf(5), slapd-config(5).
321
322

ACKNOWLEDGEMENTS

324       This module was written in 2005 by Howard Chu of Symas Corporation.
325
326
327
328OpenLDAP 2.4.40                   2014/09/20                SLAPO-ACCESSLOG(5)
Impressum