X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapo-accesslog.5;h=358fc6da661f51f5ec821cd6dec6662c21e2b061;hb=2214e47a2cf7c7776191c7e19390863cba16da6b;hp=0b1cf78c284b0c9ddac86b718dc9562145590d48;hpb=135672c91032ea90fb2897beb02972905ce36932;p=openldap diff --git a/doc/man/man5/slapo-accesslog.5 b/doc/man/man5/slapo-accesslog.5 index 0b1cf78c28..358fc6da66 100644 --- a/doc/man/man5/slapo-accesslog.5 +++ b/doc/man/man5/slapo-accesslog.5 @@ -1,9 +1,9 @@ .TH SLAPO-ACCESSLOG 5 "RELEASEDATE" "OpenLDAP LDVERSION" -.\" Copyright 2005 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 2005-2013 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .\" $OpenLDAP$ .SH NAME -slapo-accesslog \- Access Logging overlay +slapo\-accesslog \- Access Logging overlay to slapd .SH SYNOPSIS ETCDIR/slapd.conf .SH DESCRIPTION @@ -12,25 +12,24 @@ 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 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 a custom schema to assure their readability whether viewed as LDIF -or in raw form. +prune older log records from the logging database. Log records are stored +with audit schema (see below) to assure their readability whether viewed +as LDIF or in raw form. .SH CONFIGURATION These .B slapd.conf options apply to the Access Logging overlay. They should appear after the .B overlay -directive and before any subsequent -.B database directive. .TP .B logdb 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 config file. The suffix entry of the database must also already -exist. The log entries will be generated as the immediate children of the -suffix entry. +The specified database must be defined elsewhere in the configuration. +The access controls +on the log database should prevent general 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. .TP .B logops Specify which types of operations to log. The valid operation types are @@ -51,6 +50,24 @@ abandon, bind, unbind all operations .RE .TP +.B logbase +Specify a set of operations that will only be logged if they occur under +a specific subtree of the database. The operation types are as above for +the +.B logops +setting, and delimited by a '|' character. +.TP +.B logold +Specify a filter for matching against Deleted and Modified entries. If +the entry matches the filter, the old contents of the entry will be +logged along with the current request. +.TP +.B logoldattr ... +Specify a list of attributes whose old contents are always logged in +Modify and ModRDN requests. Usually only the contents of attributes that were +actually modified will be logged; by default no old attributes are logged +for ModRDN requests. +.TP .B logpurge 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 @@ -58,14 +75,14 @@ and how often to scan the database for old entries. Both the and .B interval are specified as a time span in days, hours, minutes, and seconds. The -time format is [dd+]hh:mm[:ss] i.e., the days and seconds components are -optional but hours and minutes are required. Each numeric field must be -exactly two digits. For example +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 .RS .RS .PD 0 .TP -logpurge 02+00:00 01+00:00 +logpurge 2+00:00 1+00:00 .RE .PD would specify that the log database should be scanned every day for old @@ -74,27 +91,51 @@ log database that supports ordered indexing on generalizedTime attributes, specifying an eq index on the .B reqStart attribute will greatly benefit the performance of the purge operation. +.RE +.TP +.B 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. .SH EXAMPLES .LP .nf - database bdb - suffix cn=log - \... - index reqStart eq - database bdb 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 bdb + suffix cn=log + \... + index reqStart eq + access to * + by dn.base="cn=admin,dc=example,dc=com" read .fi -.SH OBJECT CLASSES +.SH SCHEMA The .B accesslog -overlay defines a number of object classes for use in the logs. There is +overlay utilizes the "audit" schema described herein. +This schema is specifically designed for +.B accesslog +auditing and is not intended to be used otherwise. It is also +noted that the schema described here is +.I a work in +.IR 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. + +There is a basic .B auditObject class from which two additional classes, @@ -116,7 +157,7 @@ class is as follows: SUP top STRUCTURAL MUST ( reqStart $ reqType $ reqSession ) MAY ( reqDN $ reqAuthzID $ reqControls $ reqRespControls $ - reqEnd $ reqResult $ reqMessage ) ) + reqEnd $ reqResult $ reqMessage $ reqReferral ) ) .RE .P Note that all of the OIDs used in the logging schema currently reside @@ -141,7 +182,7 @@ being logged, e.g. .BR search , etc. For extended operations, the type also includes the OID of the extended operation, e.g. -.B extended(1.2.3.4.1) +.B extended(1.1.1.1) The .B reqSession @@ -179,6 +220,11 @@ accompanied by a text error message which will be recorded in the .B reqMessage attribute. +The +.B 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 associated with the operation: @@ -210,36 +256,37 @@ The .B Add class inherits from the .B auditWriteObject -class. The Add and Modify classes are essentially the same. The +class. The Add and Modify classes are very similar. The .B 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 .RS -.RS .PD 0 .TP -attribute:<+|-|=|#> [ value] +attribute:<+|\-|=|#> [ value] +.RE .RE .PD -Where '+' indicates an Add of a value, '-' for Delete, '=' for Replace, +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. -.RE .P - .LP .RS 4 ( 1.3.6.1.4.1.4203.666.11.5.2.6 NAME 'auditBind' DESC 'Bind operation' SUP auditObject STRUCTURAL - MUST reqMethod ) + MUST ( reqVersion $ reqMethod ) ) .RE .P The .B Bind -class just adds the +class includes the +.B reqVersion +attribute which contains the LDAP protocol version specified in the Bind +as well as the .B reqMethod attribute which contains the Bind Method used in the Bind. This will be the string @@ -268,24 +315,63 @@ attribute carries the Attribute Value Assertion used in the compare request. .LP .RS 4 ( 1.3.6.1.4.1.4203.666.11.5.2.8 + NAME 'auditDelete' + DESC 'Delete operation' + SUP auditWriteObject STRUCTURAL + MAY reqOld ) +.RE +.P +The +.B Delete +operation needs no further parameters. However, the +.B reqOld +attribute may optionally be used to record the contents of the entry prior +to its deletion. The values are formatted as +.RS +.PD 0 +.TP +attribute: value +.RE +.PD +The +.B reqOld +attribute is only populated if the entry being deleted matches the +configured +.B logold +filter. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.9 NAME 'auditModify' DESC 'Modify operation' SUP auditWriteObject STRUCTURAL - MUST reqMod ) + MAY reqOld MUST reqMod ) .RE .P The .B Modify -operation has already been described. +operation contains a description of modifications in the +.B reqMod +attribute, which was already described above in the Add operation. It may +optionally contain the previous contents of any modified attributes in the +.B reqOld +attribute, using the same format as described above for the Delete operation. +The +.B reqOld +attribute is only populated if the entry being modified matches the +configured +.B logold +filter. .LP .RS 4 -( 1.3.6.1.4.1.4203.666.11.5.2.9 +( 1.3.6.1.4.1.4203.666.11.5.2.10 NAME 'auditModRDN' DESC 'ModRDN operation' SUP auditWriteObject STRUCTURAL MUST ( reqNewRDN $ reqDeleteOldRDN ) - MAY reqNewSuperior ) + MAY ( reqNewSuperior $ reqOld ) ) .RE .P The @@ -304,14 +390,22 @@ The .B reqNewSuperior attribute carries the DN of the new parent entry if the request specified the new parent. +The +.B reqOld +attribute is only populated if the entry being modified matches the +configured +.B logold +filter and contains attributes in the +.B logoldattr +list. .LP .RS 4 -( 1.3.6.1.4.1.4203.666.11.5.2.10 +( 1.3.6.1.4.1.4203.666.11.5.2.11 NAME 'auditSearch' DESC 'Search operation' SUP auditReadObject STRUCTURAL - MUST ( reqScope $ reqAttrsOnly ) + MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly ) MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $ reqTimeLimit ) ) .RE @@ -320,12 +414,22 @@ For the .B Search class the .B reqScope -attribute contains the scope of the original search request, i.e. +attribute contains the scope of the original search request, using the +values specified for the LDAP URL format. I.e. .BR base , -.BR onelevel , -.BR subtree , +.BR one , +.BR sub , or -.BR subordinate . +.BR subord . +The +.B reqDerefAliases +attribute is one of +.BR never , +.BR finding , +.BR searching , +or +.BR always , +denoting how aliases will be processed during the search. The .B reqAttrsOnly attribute is a Boolean value showing @@ -352,7 +456,7 @@ attributes indicate what limits were requested on the search operation. .LP .RS 4 -( 1.3.6.1.4.1.4203.666.11.5.2.11 +( 1.3.6.1.4.1.4203.666.11.5.2.12 NAME 'auditExtended' DESC 'Extended operation' SUP auditObject STRUCTURAL @@ -379,7 +483,8 @@ as for security/audit logging purposes. ETCDIR/slapd.conf default slapd configuration file .SH SEE ALSO -.BR slapd.conf (5). +.BR slapd.conf (5), +.BR slapd\-config (5). .SH ACKNOWLEDGEMENTS .P