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.   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 en‐
31              tries will be generated as the immediate children of the  suffix
32              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 oc‐
51              cur  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 en‐
57              tries. If the entry matches the filter, the old contents of  the
58              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 de‐
64              fault 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 re‐
86              quests 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  de‐
111       scribed here is a work in progress, and hence subject to change without
112       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  re‐
153       quest,  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  re‐
163       sponse, respectively. The attribute values are just uninterpreted octet
164       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 er‐
168       ror 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  us‐
215       ing 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 Attri‐
225       bute 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 re‐
249       qMod attribute, which was already described above in the Add operation.
250       It  may  optionally  contain  the previous contents of any modified at‐
251       tributes 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  at‐
268       tribute  is only populated if the entry being modified matches the con‐
269       figured logold filter and contains attributes in the logoldattr list.
270
271
272           (  1.3.6.1.4.1.4203.666.11.5.2.11
273               NAME 'auditSearch'
274               DESC 'Search operation'
275               SUP auditReadObject STRUCTURAL
276               MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly )
277               MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $
278                     reqTimeLimit ) )
279
280       For the Search class the reqScope attribute contains the scope  of  the
281       original  search  request,  using the values specified for the LDAP URL
282       format. I.e.  base, one, sub, or subord.  The reqDerefAliases attribute
283       is  one  of  never, finding, searching, or always, denoting how aliases
284       will be processed during the search.  The reqAttrsOnly attribute  is  a
285       Boolean  value  showing TRUE if only attribute names were requested, or
286       FALSE if attributes and their values were requested.  The reqFilter at‐
287       tribute carries the filter used in the search request.  The reqAttr at‐
288       tribute lists the requested attributes if specific attributes were  re‐
289       quested.  The reqEntries attribute is the integer count of how many en‐
290       tries were returned by this search request.  The reqSizeLimit and  req‐
291       TimeLimit  attributes indicate what limits were requested on the search
292       operation.
293
294
295           (  1.3.6.1.4.1.4203.666.11.5.2.12
296               NAME 'auditExtended'
297               DESC 'Extended operation'
298               SUP auditObject STRUCTURAL
299               MAY reqData )
300
301       The Extended class represents an  LDAP  Extended  Operation.  As  noted
302       above,  the  actual OID of the operation is included in the reqType at‐
303       tribute of the parent class. If any optional data was provided with the
304       request,  it  will be contained in the reqData attribute as an uninter‐
305       preted octet string.
306
307

NOTES

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

FILES

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

SEE ALSO

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

ACKNOWLEDGEMENTS

323       This module was written in 2005 by Howard Chu of Symas Corporation.
324
325
326
327OpenLDAP                          2021/06/03                SLAPO-ACCESSLOG(5)
Impressum