ibexa

Path

ez publish / technical manual / 4.x / features / audit trailing


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

Audit trailing

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

It is possible to automatically generate audit logs based on what the users are doing with the system. This feature can be useful for big sites with many administrators and editors where information about various operations should be logged and stored. For example, auditing makes it possible to find out which user that removed content, from which IP address the request came from and so on.

The system provides a set of built-in audit functions that make it possible to generate audit logs for different types of activities. At minimum, for every operation, the system logs the following information:

  •  When it happened (time-stamp)
  •  Where the request came from (IP address)
  •  Which user that did it (username and ID number)

Note that most audit functions provide additional information. The following example shows how a record in one of the log files look like after a node has been moved.

[ May 23 2007 14:47:58 ] [127.0.0.1] [editor:16]
Node ID: 124
Old parent node ID: 2
New parent node ID: 59
Object ID: 114
Content Name: Folder
Comment: Moved the node to the given node: eZContentObjectTreeNode::move()

The following table shows the available built-in audit functions along with when they are triggered, what kind of information that is actually logged and the default log file where the information is stored.

Audit function

Activity

Logged information

Default log file

user-login

Successful login attempts

  •  Timestamp
  •  IP address
  •  User (name:ID)

login.log

user-failed-login

Failed login attempts

  •  Timestamp
  •  IP address
  •  User (name:ID)

failed_login.log

content-move

Location change of content

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Old parent node ID
  •  New parent node ID
  •  Object ID
  •  Object name
  •  Comment

content_move.log

content-delete

Removal of content

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Node ID
  •  Object ID
  •  Object name
  •  Comment

content_delete.log

role-change

Role and policy changes

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Role ID
  •  Role name
  •  Comment

role_change.log

role-assign

Role assignment to users and groups

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Role ID
  •  Role name
  •  Object name
  •  Comment

role_assign.log

section-assign

Section assignments

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Section ID
  •  Section name
  •  Node ID
  •  Object ID
  •  Object name
  •  Comment

section_assign.log

order-delete

Removal of webshop orders

  •  Timestamp
  •  IP address
  •  User (name:ID)
  •  Order ID
  •  Comment

order_delete.log

Configuration

By default, the auditing feature is turned off. In order to use audit trailing on your site, enable the "Audit" setting located in the "[AuditSettings]" section of an override for the "audit.ini" configuration file. Using the "AuditFileNames" configuration array located in the same file, you can specify which types of activities that should be logged (which audit functions that should be used) and to which files they should be logged. The audit function names must be the array keys and the log file names should be the values. Note that the default configuration logs everything to a collection of files (refer to the table in the previous section for details).

The "LogDir" setting can be used to specify where the audit log files should be stored. The default directory is "log/audit". This path refers tp VarDir setting, defined in site.ini.

Example

Let's say that you wish to audit successful log-in attempts and changes to roles and policies while ignoring all other activities. Start by creating an override for "audit.ini" and making sure that it contains the following lines:

[AuditSettings]
Audit=enabled
LogDir=log/my_audit
AuditFileNames[]
AuditFileNames[user-login]=login.log
AuditFileNames[role-change]=role_change.log

Information about successful log-in attempts will end up in the "login.log" file. Information about role and policy changes will be put in the "role_change.log" file. Both files will be located in the "<VarDir>/log/my_audit" directory. Each record in these files will contain a time-stamp pointing to the exact date and time when an operation was performed, which user that is associated with it (username and ID number) and which IP address the request came from. Records related to role and policy changes will have additional information.

Creating new audit functions

This section provides tips for PHP developers who want to create their own audit functions.

Sometimes you may need to create a new audit function, i.e. to make the system log information about a specific operation to a particular audit log file. For example, if you wish to create a new audit function called "my-new-audit" and store information about operations to a file called "info.log", you can do the following:

  1. Make sure that the "Audit" setting located in the [AuditSettings] section of an override for "audit.ini" is enabled and add a new element to the "AuditFileNames" configuration array by inserting the following line:

    AuditFileNames[my-new-audit]=info.log
    
  2. In the PHP code which defines the operation that should be logged, you can do something like this:

    eZAudit::writeAudit( 'my-new-audit', array( 'User id' => $userID,
           'Comment' => 'The operation XYZ was performed.' ) );
    

    Elements like 'Name of something' => <valueOfSomething> define which information that should be written to the "info.log" file when the operation is performed.

For example, a record in the log file can look like this:

[ May 23 2007 14:44:04 ] [127.0.0.1] [anonymous:10]
User id: 10
Comment: The operation XYZ was performed.

Julia Shymova (19/06/2007 2:20 pm)

Ricardo Correia (17/04/2013 1:43 pm)

Balazs Halasy, Julia Shymova, Svitlana Shatokhina, Geir Arne Waaler, André R., Andrea Melo, Ricardo Correia


Comments

  • new audit function

    New audit function - You say:
    <<
    In the PHP code which defines the operation that should be logged, you can do something like this:
    [..............]
    >>

    I would like to have audit's logs concerning the view operations done by users .
    Which is the php page I should modify and where is it?
    Can you write an example audit function to reach this pourpose ?

    Thanks