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  ac‐
14       tivity on a given database to be reviewed using arbitrary LDAP queries,
15       instead of just logging to local flat text files. Configuration options
16       are  available for selecting a subset of operation types to log, and to
17       automatically prune older log records from the logging  database.   Log
18       records  are stored with audit schema (see below) to assure their read‐
19       ability 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 and must support an ordered return of results
29              such as slapd-mdb(5) The access controls  on  the  log  database
30              should prevent general access. The suffix entry of the log data‐
31              base will be created automatically by this overlay. The log  en‐
32              tries  will be generated as the immediate children of the suffix
33              entry.
34
35       logops <operations>
36              Specify which types of operations to log.  The  valid  operation
37              types are abandon, add, bind, compare, delete, extended, modify,
38              modrdn, search, and unbind. Aliases for common  sets  of  opera‐
39              tions are also available:
40
41              writes add, delete, modify, modrdn
42
43              reads  compare, search
44
45              session
46                     abandon, bind, unbind
47
48              all    all operations
49
50       logbase <operations> <baseDN>
51              Specify a set of operations that will only be logged if they oc‐
52              cur under a specific subtree  of  the  database.  The  operation
53              types  are  as  above for the logops setting, and delimited by a
54              '|' character.
55
56       logold <filter>
57              Specify a filter for matching against Deleted and  Modified  en‐
58              tries.  If the entry matches the filter, the old contents of the
59              entry will be logged along with the current request.
60
61       logoldattr <attr> ...
62              Specify a list of  attributes  whose  old  contents  are  always
63              logged  in Modify and ModRDN requests that match any of the fil‐
64              ters configured in logold.  Usually only  the  contents  of  at‐
65              tributes  that were actually modified will be logged; by default
66              no old attributes are logged for ModRDN requests.
67
68       logpurge <age> <interval>
69              Specify the maximum age for log entries to be  retained  in  the
70              database,  and  how  often to scan the database for old entries.
71              Both the age and interval are specified as a time span in  days,
72              hours, minutes, and seconds. The time format is [ddd+]hh:mm[:ss]
73              i.e., the days and seconds components are optional but hours and
74              minutes are required. Except for days, which can be up to 5 dig‐
75              its, each numeric field must be exactly two digits. For example
76                     logpurge 2+00:00 1+00:00
77              would specify that the log database should be scanned every  day
78              for  old  entries,  and  entries  older  than two days should be
79              deleted. When using a log database that supports ordered  index‐
80              ing on generalizedTime attributes, specifying an eq index on the
81              reqStart attribute will greatly benefit the performance  of  the
82              purge operation.
83
84       logsuccess TRUE | FALSE
85              If  set to TRUE then log records will only be generated for suc‐
86              cessful requests, i.e., requests that produce a result code of 0
87              (LDAP_SUCCESS).  If FALSE, log records are generated for all re‐
88              quests whether they succeed or not. The default is FALSE.
89
90

EXAMPLES

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

SCHEMA

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

NOTES

325       The Access Log implemented by this overlay may be used for a variety of
326       other  tasks,  e.g. as a ChangeLog for a replication mechanism, as well
327       as for security/audit logging purposes.
328
329

FILES

331       /etc/openldap/slapd.conf
332              default slapd configuration file
333

SEE ALSO

335       slapd.conf(5), slapd-config(5).
336
337

ACKNOWLEDGEMENTS

339       This module was written in 2005 by Howard Chu of Symas Corporation.
340
341
342
343OpenLDAP 2.6.2                    2022/05/04                SLAPO-ACCESSLOG(5)
Impressum